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.
| HLINEAPP hLineApp,
| DWORD dwDeviceID,
| LPHLINE lphLine,
| DWORD dwAPIVersion,
| DWORD dwExtVersion,
| DWORD dwCallbackInstance,
| DWORD dwPrivileges,
| DWORD dwMediaModes,
| LPLINECALLPARAMS const lpCallParams
A handle to the application's registration with TAPI.
Identifies the line device to be opened. It can either be a valid device ID or
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.
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.
The API version number under which the application and Telephony API have
agreed to operate. This number is obtained with lineNegotiateAPIVersion
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
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.
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:
The application wants to make only outbound calls.
The application only wants to monitor inbound and outbound calls.
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.
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
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.
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 lineProxyResponse
, 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
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.
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
The application wants to handle calls of unknown media type (unclassified
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.
Voice energy is present on the call. The voice is locally handled by an
The application wants to handle calls with the data-modem media mode.
The application wants to handle calls of the group 3 fax media type.
The application wants to handle calls with the TDD (Telephony Devices for the
Deaf) media mode.
The application wants to handle calls of the group 4 fax media type.
The application wants to handle calls of the digital-data media type.
The application wants to handle calls with the teletex media mode.
The application wants to handle calls with the videotex media mode.
The application wants to handle calls with the telex media mode.
The application wants to handle calls with the ISDN mixed media mode.
The application wants to handle calls with the ADSI (Analog Display Services
Interface) media mode.
The media mode of the call is VoiceView.
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.
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,
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
(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
. 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
. 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,
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
variably sized field.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages