TAPI Call Handles Returned from an Asynchronous LINE_REPLY

ID: Q132191

1.00 4.00 | 4.00

WINDOWS   | WINDOWS NT

kbprg

The information in this article applies to:

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

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
   }

KBCategory: kbprg KBSubcategory: TAPI Additional reference words: 1.00 4.00

Keywords          : kbTAPI Tapi 
Version           : 1.00 4.00 | 4.00
Platform          : NT WINDOWS

Last Reviewed: August 5, 1998