TAPI Resource Cleanup

TAPI maintains its resources in a hierarchy and will perform automatic cleanup based on the hierarchy of objects.

The top of the TAPI resource hierarchy is the HLINEAPP which represents a TAPI client application instance. It is returned from lineInitialize and lineInitializeEx. If the application calls lineShutdown with its HLINEAPP, then all TAPI resources associated with the HLINEAPP will be deleted. An application may have more than one HLINEAPP.

The next level of the TAPI resource hierarchy is the HLINE which represents an open handle to a TAPI line device, returned from lineOpen. An HLINE is closed with lineClose.

Below HLINE is the HCALL which represents an open handle to a call. HCALLs are unique since TAPI will allocate them behalf of an application with an open line device (HLINE) in order to indicate call status messages to the application. An HCALL is also allocated by calling certain TAPI functions, for instance lineMakeCall. An HCALL is closed with lineDeallocateCall. Since TAPI automatically allocates HCALLs for an application, it is most efficient for the application to call lineDeallocateCall when it receives the LINE_CALLSTATE message with the LINECALLSTATE_IDLE state.

The bottom of the hierarchy is the LINEMESSAGE. A LINEMESSAGE may be associated with an HLINEAPP, an HLINE or an HCALL. There is no application control over the allocation or freeing of LINEMESSAGEs. An application needs to be aware that when it closes or frees an HLINEAPP, HLINE or HCALL, then TAPI will delete all pending LINEMESSAGEs associated with that resource. When an application closes one of the higher level objects, it should no longer wait for any messages associated with the object.

In summary:

Closing an HCALL (lineDeallocateCall) deletes all pending LINEMESSAGEs associated with it.

Closing an HLINE (lineClose) closes all HCALLs associated with it.

Closing an HLINEAPP (lineShtudown) closes all associated HLINEs.

In Windows CE, TAPI is implemented as a PSL (Protected Server Library), so it gets a notification when a process terminates. When a process terminates, TAPI closes all HLINEAPPs associated with the process.

Author: David Kanz