Platform SDK: TAPI

phoneInitializeEx

The phoneInitializeEx function initializes the application's use of TAPI for subsequent use of the phone abstraction. It registers the application's specified notification mechanism and returns the number of phone devices available to the application. A phone device is any device that provides an implementation for the phone-prefixed functions in the Telephony API.

LONG WINAPI phoneInitializeEx(
  LPHPHONEAPP lphPhoneApp,                             
  HINSTANCE hInstance,                                 
  PHONECALLBACK lpfnCallback,                          
  LPCSTR lpszFriendlyAppName,                          
  LPDWORD lpdwNumDevs,                                 
  LPDWORD lpdwAPIVersion,                              
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams  
);

Parameters

lphPhoneApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see phoneCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
lpszFriendlyAppName
A pointer to a null-terminated string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application has ownership of the phone device. If lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by the Windows function GetModuleFileName).
lpdwNumDevs
A pointer to a DWORD. Upon successful completion of this request, this location is filled with the number of phone devices available to the application.
lpdwAPIVersion
A pointer to a DWORD. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of phoneNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set. TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.
lpPhoneInitializeExParams
A pointer to a structure of type PHONEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If PHONEERR_REINIT is returned and TAPI reinitialization has been requested (for example, as a result of adding or removing a telephony service provider), then phoneInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call phoneInitializeEx.

If the PHONEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual phone devices by using phone device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these phone devices are capable of any particular TAPI function without first querying their device capabilities by phoneGetDevCaps.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later.
  Version: Requires TAPI 2.0 or later.
  Header: Declared in Tapi.h.
  Library: Use Tapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, phoneCallbackFunc, phoneGetDevCaps, phoneGetMessage, PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneNegotiateAPIVersion, phoneShutdown, PHONESTATUS