| Platform SDK: TAPI |
Assume that the service provider must display a dialog box (like the Unimodem or ATSP Talk/Hangup dialog box) during the processing of lineMakeCall or lineDial. In this case, it is the service provider, not the application, that decides that UI must be displayed.
To invoke the UI DLL in the application process, the service provider calls the TSPI LINEEVENT callback, generating a LINE_CREATEDIALOGINSTANCE message, passing in a pointer to a structure of type TUISPICREATEDIALOGINSTANCEPARAMS. This structure contains the dwRequestID of the function with which the UI is associated, allowing TAPISRV to identify the client application in which the UI is to be generated.
TAPISRV requests the correct application's instance of TAPI to load the UI DLL and create a thread for the UI within the application's process. From this new UI thread, TAPI calls the UI DLL's TUISPI_providerGenericDialog function, passing in data that was specified by the telephony service provider in the structure passed in with the LINE_CREATEDIALOGINSTANCE message; the UI DLL displays the appropriate dialog box (which is a matter for private design between the UI DLL and the telephony service provider). The UI DLL does not return from TUISPI_providerGenericDialog until the dialog box is closed.
The telephony service provider can generate updated data to display in the dialog box (or, for example, instruct the dialog box to be closed, if the call is abandoned or other events occur) by sending a LINE_SENDDIALOGINSTANCEDATA message. TAPISRV conveys the data to TAPI, which calls the UI DLL's TUISPI_providerGenericDialogData function. This mechanism provides a unidirectional "send" to the UI DLL. If the UI DLL wants to inform the telephony service provider of the results of the dialog box or obtain other data, it can call the TUISPIDLLCALLBACK function (a pointer to which it received when TUISPI_providerGenericDialog was called).
When the dialog box is dismissed, TUISPI_providerGenericDialog returns to TAPI. TAPI calls FreeLibrary to release the UI DLL, and exits the UI thread it had created in the application context. It then requests TAPISRV to call the telephony service provider's TSPI_providerFreeDialogInstance function to unbind the association created when the telephony service provider originally sent the LINE_CREATEDIALOGINSTANCE message. This function is also called if the application process terminates unexpectedly before TUISPI_providerGenericDialog returns.