Creates a handle and associates it with a service specific value.
DWORD dispCreateHandle (CTAHD ctahd, unsigned svcid, unsigned value, unsigned *hd)
|
Argument |
Description |
|
ctahd |
Context handle. |
|
svcid |
Identifier of the requesting service. |
|
value |
Single 32-bit value associated with the handle. |
|
hd |
Pointer to the returned handle. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_BAD_ARGUMENT |
hd pointer is NULL. |
|
CTAERR_INVALID_CTAHD |
The specified ctahd is invalid. |
|
CTAERR_NOT_INITIALIZED |
Natural Access was not initialized. |
|
CTAERR_OUT_OF_MEMORY |
Unable to allocate memory for the handle. |
|
CTAERR_OUT_OF_RESOURCES |
Unable to find free space in internal tables (maximum number of handles is 64 K). |
|
CTAERR_SERVICE_NOT_AVAILABLE |
The specified service is not initialized. |
dispCreateHandle 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 can 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 do 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 is 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 handles 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.
dispAttachHandle, dispFindHandle, dispFindHandleByName, dispGetHandleValueEx, dispSetHandleValueEx