Destroys the API handle and clears its associated value.
DWORD dispDestroyHandle (unsigned hd)
|
Argument |
Description |
|
hd |
Handle returned by dispCreateHandle. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_INVALID_HANDLE |
An invalid handle was passed as an argument to this function. |
|
CTAERR_NOT_INITIALIZED |
Natural Access was not initialized. |
dispDestroyHandle is used when an API closes or destroys a server side object to remove the association between the API handle and the server-side handle.
API handles are a limited resource so they must be destroyed when the object they reference is destroyed. Otherwise, a handle leak occurs and future API calls can return CTAERR_OUT_OF_RESOURCES.
API handles associated with open server-side objects are automatically cleaned up when a service is closed. Services do not need to worry about handle leaks. Services must ensure that the server-side objects are cleaned up properly, or other resource leaks will occur.
dispAttachHandle, dispFindHandle, dispFindHandleByName, dispGetHandleValue, dispGetHandleValueEx, dispSetHandleValue, dispSetHandleValueEx