Deallocating a Call

If an application is finished with a call and another application wants the call, the call can be handed off. But if no other applications want to take ownership, there is nothing to do but deallocate the call's handle. This is done with lineDeallocateCall. A call handle is no longer valid after it has been deallocated.

In contrast, dropping (disconnecting) a call puts the call in the idle state, which means that the local end of the connection is on hook. If the other end of the connection drops the call, the call transitions to the disconnected state, not the idle state. Typically, once an application receives a call-state message indicating the disconnected state, it immediately drops the call, causing it to become idle. Although the call is in the idle state, any handles to it held by applications remain valid until they are deallocated. If the call was never answered (the local end never went off hook), it may revert to the idle state without being dropped.

An application cannot deallocate a call if it is the sole owner and the call's state is not idle. This is because TAPI tries to ensure that there is always at least one owner for every active call. If the application is the sole owner and the call is not idle, the error message LINEERR_INVALCALLSTATE is returned. If an application needs to circumvent this restriction, it can do so by dropping the call first (with lineDrop) and then deallocating its handle. This prevents an application from deallocating its handle which would result in a call disconnect. By making the application do an explicit drop, it can inform the user (in a dialog box) that the call is about to be disconnected.

If releasing the ownership handle results in the call's having no more handles, TAPI calls the service provider function TSPI_lineCloseCall. When this function is invoked on a call that is not yet idle, it is up to the service provider to drop the call.

Note  An application that has monitor privileges for a call can always deallocate its handle for the call. Deallocating a call does not affect the call state of the physical call, but it does release the internal resources (memory) related to the call.

An application should deallocate the handle to a call it owns in these two cases:

Failure to deallocate call handles in a timely way can result in system failure and lost calls due to unnecessary consumption of memory and other resources.