This function initializes the application’s use of Tapi.dll for subsequent use of the line abstraction. It registers the application’s specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in TAPI.
At a Glance
| Header file: | Tapi.h |
| Windows CE versions: | 1.0 and later |
Syntax
LONG lineInitialize(LPHLINEAPP lphLineApp, HINSTANCE hInstance, LINECALLBACK lpfnCallback, LPCTSTR lpszAppName,
LPDWORD lpdwNumDevs);
Parameters
lphLineApp
[out] Pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
[in] Instance handle of the client application or DLL.
lpfnCallback
[in] Pointer to a callback function that is invoked to determine status and events on the line device, addresses, or calls. For more information, see lineCallbackFunc.
lpszAppName
[in] Pointer to a null-terminated string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This data can be useful for call logging purposes. If lpszAppName is NULL, the application's filename is used instead.
lpdwNumDevs
[out] Pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.
Return Values
Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:
| LINEERR_INVALAPPNAME | LINEERR_REINIT |
| LINEERR_OPERATIONFAILED | LINEERR_NODRIVER |
| LINEERR_INIFILECORRUPT | LINEERR_NODEVICE |
| LINEERR_RESOURCEUNAVAIL | LINEERR_NOMEM |
| LINEERR_INVALPOINTER | LINEERR_NOMULTIPLEINSTANCE |
Remarks
If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example as a result of adding or removing a telephony service provider), then lineInitialize requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call lineInitialize. If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.
The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of anything beyond what is specified by the Basic Telephony subset without first querying their device capabilities using lineGetDevCaps.
Applications should not invoke lineInitialize without subsequently opening a line (at least for monitoring). If the application is not monitoring and not using any devices, it should call lineShutdown so that memory resources allocated by Tapi.dll can be released if unneeded, and Tapi.dll itself can be unloaded from memory while not needed.
Another reason for performing a lineShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. After a reconfiguration has taken place, causing a LINEDEVSTATE_REINIT message to be sent, no applications can open a device until all applications have performed a lineShutdown. If any service provider fails to initialize properly, this function fails and returns the error indicated by the service provider.
See Also