lineOpen
The lineOpen
function opens the line device specified by its device ID and returns a line
handle for the corresponding opened line device. This line handle is used in subsequent
operations on the line device.
LONG lineOpen(
|
HLINEAPP hLineApp, |
|
|
DWORD dwDeviceID, |
|
|
LPHLINE lphLine, |
|
|
DWORD dwAPIVersion, |
|
|
DWORD dwExtVersion, |
|
|
DWORD dwCallbackInstance, |
|
|
DWORD dwPrivileges, |
|
|
DWORD dwMediaModes, |
|
|
LPLINECALLPARAMS const lpCallParams |
|
|
); |
|
Parameters
hLineApp
A handle to
the application's registration with TAPI.
dwDeviceID
Identifies
the line device to be opened. It can either be a valid device ID or the value:
LINEMAPPER
This value is
used to open a line device in the system that supports the properties specified
in lpCallParams. The application can use lineGetID to determine the ID of the
line device that was opened.
lphLine
A pointer to
an HLINE handle, which is then loaded with the handle representing the opened
line device. Use this handle to identify the device when invoking other
functions on the open line device.
dwAPIVersion
The API
version number under which the application and Telephony API have agreed to
operate. This number is obtained with lineNegotiateAPIVersion.
dwExtVersion
The extension
version number under which the application and the service provider agree to
operate. This number is zero if the application does not use any extensions. This
number is obtained with lineNegotiateExtVersion.
dwCallbackInstance
User-instance
data passed back to the application with each message associated with this line
or addresses or calls on this line. This parameter is not interpreted by the
Telephony API.
dwPrivileges
The privilege
the application wants for the calls it is notified for. This parameter can be a
combination of the LINECALLPRIVILEGE_ constants. For applications using API
version 0x00020000 or greater, values for this parameter can also be combined
with the LINEOPENOPTION_ constants:
LINECALLPRIVILEGE_NONE
The
application wants to make only outbound calls.
LINECALLPRIVILEGE_MONITOR
The
application only wants to monitor inbound and outbound calls.
LINECALLPRIVILEGE_OWNER
The
application wants to own inbound calls of the types specified in dwMediaModes.
LINECALLPRIVILEGE_MONITOR
+ LINECALLPRIVILEGE_OWNER
The
application wants to own inbound calls of the types specified in dwMediaModes,
but if it cannot be an owner of a call, it wants to be a monitor.
LINEOPENOPTION_SINGLEADDRESS
The
application is interested only in new calls that appear on the address
specified by the dwAddressID field in the LINECALLPARAMS structure pointed to by the
lpCallParams parameter (which must be specified). If
LINEOPENOPTION_SINGLEADDRESS is specified but either lpCallParams is
invalid or the included dwAddressID does not exist on the line, the open
fails with LINERR_INVALADDRESSID.
In addition to setting the dwAddressID member of the LINECALLPARAMS
structure to the desired address, the application must also set dwAddressMode
in LINECALLPARAMS to LINEADDRESSMODE_ADDRESSID.
The LINEOPENOPTION_SINGLEADDRESS option affects only TAPI's assignment
of initial call ownership of calls created by the service provider using
a LINE_NEWCALL message. An application that opens the line with
LINECALLPRIVILEGE_MONITOR will continue to receive monitoring handles to all
calls created on the line. Furthermore, the application is not restricted in
any way from making calls or performing other operations that affect other
addresses on the line opened.
LINEOPENOPTION_PROXY
The application
is willing to handle certain types of requests from other applications that
have the line open, as an adjunct to the service provider. Requests will be
delivered to the application using LINE_PROXYREQUEST messages; the application
responds to them by calling lineProxyResponse32C9WDF, and can also generate TAPI messages to
other applications having the line open by calling lineProxyMessage.
When this option is specified, the application must also specify which
specific proxy requests it is prepared to handle. It does so by passing, in the
lpCallParams parameter, a pointer to a LINECALLPARAMS structure in which the dwDevSpecificSize
and dwDevSpecificOffset members have been set to delimit an array of
DWORDs. Each element of this array shall contain one of the LINEPROXYREQUEST_
constants. For example, a proxy handler application that supports all five of
the Agent-related functions would pass in an array of five DWORDs (dwDevSpecificSize
would be 20 decimal) containing the five defined LINEPROXYREQUEST_ values.
The proxy request handler application can run on any machine that has
authorization to control the line device. However, requests will always be
routed through the server on which the service provider is executing that
actually controls the line device. Thus, it is most efficient if the
application handling proxy requests (such as ACD agent control) executes
directly on the server along with the service provider.
Subsequent attempts, by the same application or other applications, to
open the line device and register to handle the same proxy requests as an
application that is already registered fail with LINEERR_NOTREGISTERED.
To stop handling requests on the line, the application simply calls lineClose.
Other flag combinations return the LINEERR_INVALPRIVSELECT error.
dwMediaModes
The media
mode or modes of interest to the application. This parameter is used to register
the application as a potential target for inbound call and call handoff for the
specified media mode. This parameter is meaningful only if the bit
LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is
not). This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
The
application wants to handle calls of unknown media type (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE
The
application wants to handle calls of the interactive voice media type. That is,
it manages voice calls with the human user on this end of the call.
LINEMEDIAMODE_AUTOMATEDVOICE
Voice energy
is present on the call. The voice is locally handled by an automated
application.
LINEMEDIAMODE_DATAMODEM
The
application wants to handle calls with the data-modem media mode.
LINEMEDIAMODE_G3FAX
The
application wants to handle calls of the group 3 fax media type.
LINEMEDIAMODE_TDD
The
application wants to handle calls with the TDD (Telephony Devices for the Deaf)
media mode.
LINEMEDIAMODE_G4FAX
The
application wants to handle calls of the group 4 fax media type.
LINEMEDIAMODE_DIGITALDATA
The
application wants to handle calls of the digital-data media type.
LINEMEDIAMODE_TELETEX
The
application wants to handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The
application wants to handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The
application wants to handle calls with the telex media mode.
LINEMEDIAMODE_MIXED
The
application wants to handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
The
application wants to handle calls with the ADSI (Analog Display Services Interface)
media mode.
LINEMEDIAMODE_VOICEVIEW
The media
mode of the call is VoiceView.
lpCallParams
A pointer to
a structure of type LINECALLPARAMS. This pointer is only used if LINEMAPPER is
used; otherwise lpCallParams is ignored. It describes the call parameter
that the line device should be able to provide.
Return Values
Returns zero
if the request is successful or a negative error number if an error has
occurred. Possible return values are:
LINEERR_ALLOCATED,
LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER,
LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION,
LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL,
LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER,
LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE,
LINEERR_OPERATIONUNAVAIL.
Remarks
If LINEERR_ALLOCATED
is returned, the line cannot be opened due to a "persistent"
condition, such as that of a serial port being exclusively opened by another
process. If LINEERR_RESOURCEUNAVAIL is returned, the line cannot be opened due
to a dynamic resource overcommitment such as in DSP processor cycles or memory.
This overcommitment may be transitory, caused by monitoring of media mode or
tones, and changes in these activities by other applications may make it possible
to reopen the line within a short time period. 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 lineOpen 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.
Opening a
line always entitles the application to make calls on any address available on
the line. The ability of the application to deal with inbound calls or to be
the target of call handoffs on the line is determined by the dwMediaModes
parameter. The lineOpen function registers the application as having an
interest in monitoring calls or receiving ownership of calls that are of the
specified media modes. If the application just wants to monitor calls, then it
can specify LINECALLPRIVILEGE_MONITOR. If the application just wants to make
outbound calls, it can specify LINECALLPRIVILEGE_NONE. If the application is
willing to control unclassified calls (calls of unknown media mode), it can
specify LINECALLPRIVILEGE_OWNER and LINEMEDIAMODE_UNKNOWN. Otherwise, the
application should specify the media mode it is interested in handling.
The media modes
specified with lineOpen add to the default value for the provider's
media mode monitoring for initial inbound call type determination. The lineMonitorMedia function modifies the mask
that controls LINE_MONITORMEDIA
messages. If a line device is opened with owner privilege and an extension
media mode is not registered, then the error LINEERR_INVALMEDIAMODE is
returned.
An application
that has successfully opened a line device can always initiate calls using lineMakeCall, lineUnpark, linePickup, lineSetupConference (with a NULL hCall),
as well as use lineForward
(assuming that doing so is allowed by the device capabilities, line state, and
so on).
A single
application may specify multiple flags simultaneously to handle multiple media
modes. Conflicts may arise if multiple applications open the same line device
for the same media mode. These conflicts are resolved by a priority scheme in
which the user assigns relative priorities to the applications. Only the
highest priority application for a given media mode will ever receive ownership
(unsolicited) of a call of that media mode. Ownership can be received when an
inbound call first arrives or when a call is handed off.
Any
application (including any lower priority application) can always acquire
ownership with lineGetNewCalls or lineGetConfRelatedCalls. If an application opens a
line for monitoring at a time that calls exist on the line, LINE_CALLSTATE messages for those existing
calls are not automatically generated to the new monitoring application. The
application can query the number of current calls on the line to determine how
many calls exist, and, if it wants, it can call lineGetNewCalls to
obtain handles to these calls.
An application
that handles automated voice should also select the interactive voice open mode
and be assigned the lowest priority for interactive voice. The reason for this
is that service providers will report all voice media modes as interactive
voice. If media mode determination is not performed by the application for the
UNKNOWN media type, and no interactive voice application has opened the line device,
voice calls would be unable to reach the automated voice application, but be
dropped instead.
The same
application, or different instantiations of the same application, may open the
same line multiple times with the same or different parameters.
When an
application opens a line device it must specify the negotiated API version and,
if it wants to use the line's extensions, it should specify the line's
device-specific extension version. These version numbers should have been
obtained with lineNegotiateAPIVersion and lineNegotiateExtVersion. Version numbering allows
the mixing and matching of different application versions with different API
versions and service provider versions.
LINEMAPPER
allows an application to select a line indirectly by means of the services it wants from it. When
opening a line device using LINEMAPPER, the following is true: All fields from
beginning of the LINECALLPARAMS data structure through dwAddressMode
are relevant. If dwAddressMode is LINEADDRESSMODE_ADDRESSID it means
that any address on the line is acceptable, otherwise if dwAddressMode
is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address
(phone number) is searched for, or if it is a provider-specific extension, then
dwOrigAddressSize/Offset and the portion of the variable part they refer
to are also relevant. If dwAddressMode is a provider-specific extension
additional information may be contained in the dwDeviceSpecific variably
sized field.
See Also