Table of Contents NMS Glossary Previous Page Next Page (Page 4 of 36 in this chapter) Version

dispCreateHandle

Description

Creates a handle and associates it with a service specific value.

Prototype

DWORD dispCreateHandle ( CTAHD ctahd,
unsigned svcid,
unsigned value,
unsigned *hd)

ctahd Context handle.

svcid Identifier of the requesting service.

value Single 32-bit value associated with handle.

hd Pointer to the returned handle.

Return Values

Events

Details

This function is typically used by services to create API (client) side service handles that can then be used by API functions that implicitly reference the ctahd. Services that allow multiple opens of objects that they manage may use this function to create a handle and associate with it the ctahd and a server side handle that references the real object. The Voice Message service uses this function to create vcehds for voice objects. The Switching service uses this function to create swihds for open switches.

This extra handle translation is necessary since the API must call dispSendCommand with a valid ctahd as well as its own server side object handle. Since the API functions will not have any connection to their server side contexts in future client-server versions of Natural Access, a mapping needs to be maintained on the client side.

If only the server side object handle was passed back to the application, then every client side API would need to perform a mapping from object handle to ctahd including any locks necessary on the data structures to make the code thread safe. Instead, this functionality is incorporated into the dispatcher and made available to service writers.

An additional problem with using server side handles is that servers on different nodes could return identical handles. Although these would be on different contexts, they could be in the same client process. The client side object handles must be different from the server object handles. This is guaranteed to be the case by using the unique handle returned by this function.

The dispatcher goes through its handle table when a service is closed and removes all handle associations for the specified context and service ID. This works because all the information that the API manages is in the dispatcher handle table. The server side handle and its information is managed by the service and must be closed and cleaned up on the invocation of the close service binding function xxxCloseService.

dispSetHandleValue and dispGetHandleValue are used to modify and retrieve the server side handle associated with the API handle. dispDestroyHandle is used by the API to destroy a handle when it is being closed.

See Also

dispDestroyHandle, dispGetHandleValue, dispSetHandleValue


Table of Contents NMS Glossary Previous Page Next Page (Page 4 of 36 in this chapter) Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2001, Natural MicroSystems, Inc. All rights reserved.