PRB: ATSP Returns Error for Validated Parameter

Last reviewed: July 23, 1997
Article ID: Q108923
1.00 WINDOWS kbprg kbprb

The information in this article applies to:

  • Microsoft Windows Telephony Software Development Kit (SDK) version 1.0 for Windows version 3.1

SUMMARY

TAPI.DLL will pre-validate the device ID parameter before passing it onto the service provider. However, the ATSP sample source code provided with the TAPI (Telephony application programming interface) SDK, returns LINEERR_BADDEVICEID for calls that take device IDs as a parameter:

   TSPI_lineNegotiateTSPIVersion
   TSPI_lineConfigDialog
   TSPI_lineGetAddressCaps
   TSPI_lineOpen

The documentation correctly indicates LINEERR_BADDEVICEID is not a valid return value for these functions.

SYMPTOMS

None. Because TAPI.DLL catches the bad device ID before it is passed to the service provider, the code in ATSP is never executed.

CAUSE

The code in the ATSP sample is an artifact of an earlier (beta) version of TAPI.DLL.

RESOLUTION

Do not put code that returns LINERR_BADDEVICEID in your service provider.

MORE INFORMATION

In general, TAPI pre-validates many parameters, and the documentation explicitly indicates only those cases where a parameter is not pre- validated. Even so, there are certain places in the sample service provider in which the return codes still exist for pre-validated parameters. For example, line handles are supposed to be pre-validated, but functions in the sample service provider still have code that returns LINEERR_INVALLINEHANDLE.

This code is to handle rare race conditions where TAPI.DLL "thinks" that a line handle is still valid but the service provider doesn't think that the line handle is still valid. This race condition occurs only if the provider issues the LINE_CLOSE message, indicating the provider has closed the line, and still has messages in TAPI.DLL's internal queue waiting to be processed. If this happens while TAPI.DLL is processing a function call from an application that uses a handle that the provider made invalid when the provider issued the message, TAPI.DLL will validate the handle from the application, and therefore think the handle was OK, and the provider would have to reject the handle.

This situation should be a very rare occurrence because issuing LINE_CLOSE messages is very rare, and because the situation is most likely to occur only as the result of the user modifying the driver setup through the Control Panel. It is unlikely that some other TAPI function would be called for that same line at the same instant.


Additional reference words: 1.00 3.10
KBCategory: kbprg kbprb
KBSubcategory: Tapi
Keywords : kb16bitonly Tapi kbprb kbprg
Version : 1.00
Platform : WINDOWS


THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: July 23, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.