TAPI Call Handles Returned from an Asynchronous LINE_REPLY (132191)

This article was previously published under Q132191

Several TAPI APIs, such as lineMakeCall and lineSetupConference, take the address of a call handle as a parameter. Upon successful completion of these APIs, the address pointed at is filled with the new call handle.

TAPI does not, however, fill this address until the application receives the LINE_REPLY message indicating that the API completed successfully. Thus, not only is the handle not valid until the LINE_REPLY, but the actual address must still be valid when LINE_REPLY is received. It is recommended that stack variables not be used because they will often go out of scope before the LINE_REPLY message is received.

For example, this code fragment is incorrect:

   func()
   {
       HCALL hCall;
   ...
       AsyncID = lineMakeCall(hLine, &hCall, lpszDestAddress, 0, NULL);
   }
		

Here, lineMakeCall is going to return an asynchronous ID that will eventually have a matching LINE_REPLY message. However, by the time the LINE_REPLY message is retrieved, hCall will not be a valid variable and &hCall will not be a valid pointer. Expect a general protection (GP) fault or stack corruption.

In the following code, When LINE_REPLY for lineMakeCall is received, &g_hCall is still valid and is filled with a valid call handle:

   HCALL g_hCall;
   func()
   {
   ...
       lineMakeCall(hLine, &g_hCall, lpszDestAddress, 0, NULL);

       // g_hCall is *not* valid until LINE_REPLY is received
   }