Initialization and Shutdown in TAPI

For an application to use any of TAPI's basic or supplementary line functions, it needs a connection to TAPI through which it can receive messages. The application establishes this connection, using either the lineInitializeEx or the phoneInitializeEx function. The parameters of these functions allow the application to specify the message notification mechanism the application desires to use. Following are specifics about the initialization process:

• The initialization functions are not device-related. When an application calls an initialization function, TAPI does not act on a line or phone device or an abstraction thereof.
• The first time an initialization function is called in a telephony session, TAPI also sets up the telephony environment. Among the tasks it performs are loading the TAPI dynamic-link library and tapisrv.exe, and loading the device drivers (telephony service providers and ancillary components) specified in the registry. In addition, the communication link described above is established between TAPI and the calling application.
• The INIFILECORRUPT error can be returned if TAPI determines that the registry contains an invalid entry. When this error occurs (in lineInitializeEx and phoneInitializeEx, or another function), the user should identify and resolve the problem. It may be necessary to rebuild the registry or a portion of it, which can be done through the Telephony Control Panel.

  For example, the LINEERR_NODRIVER ("the driver was not installed") error indicates either that a service provider that was previously installed can no longer be found or that some subsidiary component of a service provider (such as a VxD) cannot be found. When this error is encountered, the application should advise the user to correct the problem with the Driver Setup function within the Telephony Control Panel.

• Although each application needs only one associated with TAPI, it can call an initialization function more than once to specify other message notification path.
• Both lineInitializeEx and lineShutdown (and the corresponding phone functions) operate synchronously. These functions return a success or failure indication, not an asynchronous request identifier.

Upon completion, the lineInitializeEx function returns two pieces of information to the application: an application handle and the number of available line devices.

• The application handle represents the application's usage of TAPI. That is, to TAPI, it represents the application. TAPI functions that use line or call handles (explained later in this section) do not require the application handle, because this handle is derived from the specified line, phone, or call handle.
• The lineInitializeEx function also returns the number of line devices available to the application through TAPI. Line devices are identified by their device identifier (device identifier). Valid device identifiers range from zero to one less than the number of line devices. For example, if lineInitializeEx reports that there are two line devices in a system, the valid line device identifiers are 0 and 1.

After an application is finished calling TAPI's line functions, it calls lineShutdown and passes its application handle to terminate its usage of TAPI. This allows TAPI to free any resources assigned to the application.