Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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.

Syntax 

LONG lineInitialize(
  LPHLINEAPP 
lphLineApp, 
  HINSTANCE 
hInstance, 
  LINECALLBACK 
lpfnCallback, 
  LPCWSTR 
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 Unicode characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFOstructure 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 lpszAppNameis NULL, the application's file name 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 Value

Zero indicates success. A negative error number indicates that an error occurred. The following table shows the return values for this function.

Value Description

LINEERR_INVALAPPNAME

Invalid application name

LINEERR_OPERATIONFAILED

The operation failed

LINEERR_INIFILECORRUPT

The INI file is corrupted

LINEERR_RESOURCEUNAVAIL

The resource is unavailable

LINEERR_INVALPOINTER

Invalid pointer

LINEERR_REINIT

The application attempted to initialize TAPI twice.

LINEERR_NODRIVER

No driver was found

LINEERR_NODEVICE

No device was found

LINEERR_NOMEM

No memory is available

LINEERR_NOMULTIPLEINSTANCE

Multiple instances were not found

Remarks

The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevsminus 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 the lineGetDevCapsfunction.

Applications should not invoke lineInitializewithout subsequently opening a line (at least for monitoring). If the application is not monitoring and not using any devices, it should call the lineShutdownfunction so that memory resources allocated by Tapi.dll can be released if not needed.

Requirements

Header tapi.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also