lineInitializeEx
The
lineInitializeEx function initializes the application's use of TAPI 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 the Telephony API.
LONG lineInitializeEx(
LPHLINEAPP lphLineApp,
|
|
HINSTANCE hInstance,
|
|
LINECALLBACK lpfnCallback,
|
|
LPCSTR lpszFriendlyAppName,
|
|
LPDWORD lpdwNumDevs,
|
|
LPDWORD lpdwAPIVersion,
|
|
LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
|
|
);
|
|
Parameters
lphLineApp
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
may pass NULL for this parameter, in which case TAPI will use the module handle
of the root executable of the process (for purposes of identifying call handoff
targets and media mode priorities).
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
lineCallbackFunc). 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 ASCII string that contains only displayable
ASCII characters. If this parameter is not NULL, it contains an
application-supplied name of 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 information can be useful for
call logging purposes. If
lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by
the Windows API
GetModuleFileName).
lpdwNumDevs
A 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.
lpdwAPIVersion
A pointer to a DWORD-sized location. 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
lineNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set
(for this release, to 0x00020000). TAPI will translate 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 (for this release, 0x00020000), thereby allowing
the application to detect and adapt to having been installed on a system with
an older version of TAPI.
lpLineInitializeExParams
A pointer to a structure of type
LINEINITIALIZEEXPARAMS 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 is successful or a negative error number if an
error has occurred. Possible return values are:
LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT,
LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_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.
The Hidden Window mechanism is selected by specifying
LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in the
dwOptions field in the
LINEINITIALIZEEXPARAMS 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
lineInitializeEx 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 API), 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
LineCallbackProc, a pointer to which the application provided as a parameter in its call to
lineInitializeEx (or
lineInitialize, for TAPI 1.3 and 1.4 applications). 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
lineShutdown function.
The Event Handle mechanism is selected by specifying
LINEINITIALIZEEXOPTION_USEEVENT in the
dwOptions field in the
LINEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the
application, and returns a handle to the object in the
hEvent field in
LINEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example,
must not call
SetEvent,
ResetEvent,
CloseHandle, and so on) or undefined behavior will result; the application may only wait
on this event using functions such as
WaitForSingleObject or
MsgWaitForMultipleObjects. TAPI will signal this event whenever a telephony event notification is
pending for the application; the application must call
lineGetMessage 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
lineShutdown function. The application is not required to wait on the event handle that is
created; the application could choose instead to call
lineGetMessage and have it block waiting for a message to be queued.
The Completion Port mechanism is selected by specifying
LINEINITIALIZEEXOPTION_USECOMPLETION PORT in the
dwOptions field in the
LINEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to
the application, TAPI will send it to the application using
PostQueuedCompletionStatus to the completion port that the application specified in the
hCompletionPort field in
LINEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the
dwCompletionKey field in
LINEINITIALIZEEXPARAMS. The application must have previously created the completion port using
CreateIoCompletionPort. The application retrieves events using
GetQueuedCompletionStatus. Upon return from
GetQueuedCompletionStatus, the application will have the specified
dwCompletionKey written to the DWORD pointed to by the
lpCompletionKey parameter, and a pointer to a
LINEMESSAGE structure returned to the location pointed to by
lpOverlapped. After the application has processed the event, it is the application's
responsibility to call
LocalFree to release the memory used to contain the
LINEMESSAGE structure. Because the application created the completion port (thereby
allowing it to be shared for other purposes), the application must close it; the
application must not close the completion port until after calling
lineShutdown.
When a multi-threaded 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 LINEERR_REINIT is returned and TAPI reinitialization has been requested,
for example as a result of adding or removing a Telephony service provider, then
lineInitializeEx requests are rejected with this error until the last application shuts down
its usage of the API (using
lineShutdown), at which time the new configuration becomes effective and applications are
once again permitted to call
lineInitializeEx.
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 IDs
that range from zero to
dwNumDevs minus one. An application should not assume that these line devices are
capable of any particular TAPI function without first querying their device
capabilities by
lineGetDevCaps and
lineGetAddressCaps.
See Also
lineCallbackFunc,
LINECALLINFO,
lineGetAddressCaps,
lineGetDevCaps,
lineGetMessage,
lineInitialize,
LINEINITIALIZEEXPARAMS,
LINEMESSAGE,
lineNegotiateAPIVersion,
lineShutdown
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database
