다음을 통해 공유

phoneInitializeEx (Compact 2013)

  • 아티클

3/26/2014

This 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.

Syntax

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

Parameters

  • lphPhoneApp
    Pointer to a location that is filled with the application's usage handle for TAPI.
  • hInstance
    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
    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. This parameter is ignored and should be set to NULL when the application chooses to use the event handle event notification mechanism.
  • lpszFriendlyAppName
    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 file name is used instead (as returned by the Windows function GetModuleFileName).
  • lpdwNumDevs
    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
    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 the phoneNegotiateAPIVersion function). 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
    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 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

PHONEERR_INVALAPPNAME

The application name is invalid.

PHONEERR_OPERATIONFAILED

The operation failed.

PHONEERR_INIFILECORRUPT

The INI file is corrupted.

PHONEERR_INVALPOINTER

The pointer is invalid.

PHONEERR_REINIT

If TAPI reinitialization has been requested, phoneInitializeEx requests are rejected with this error until the last application shuts down its usage of the function, at which time the new configuration becomes effective and applications are once again permitted to call phoneInitialize or phoneInitializeEx.

PHONEERR_NOMEM

Not enough memory is available.

PHONEERR_INVALPARAM

The specified hInstance parameter is invalid.

Remarks

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

The Hidden Window mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI 1.x applications), TAPI creates a window in the context of the application during the phoneInitializeEx function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage function), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the phoneCallbackFunc, a pointer to which the application provided as a parameter in its call to phoneInitializeEx. This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the phoneShutdown function.

The Event Handle mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in PHONEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call the phoneGetMessage function to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the phoneShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call phoneGetMessage and have it block waiting for a message to be queued.

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 using the phoneGetDevCaps function.

Requirements

Header

tapi.h

Library

TAPI32.dll

See Also

Reference

TAPI Phone Device Functions
phoneCallbackFunc
phoneGetDevCaps
phoneGetMessage
phoneNegotiateAPIVersion
phoneShutdown
PHONEINITIALIZEEXPARAMS
PHONEMESSAGE

Other Resources

CloseHandle
GetMessage
GetModuleFileName
MsgWaitForMultipleObjects
ResetEvent
WaitForSingleObject