TAPI Call Handles Returned from an Asynchronous LINE_REPLY

• Microsoft Win32 Software Development Kit (SDK) for Windows NT version 4.0
• Microsoft Win32 Software Development Kit (SDK) for Windows 95 version 4.0
• Microsoft Windows Telephony Software Development Kit (TAPI SDK) version 1.0

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);
   }

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
   }