lineOpen

This function opens the line device specified by its device identifier and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

At a Glance

Header file:	Tapi.h
Windows CE versions:	1.0 and later

Syntax

LONG lineOpen(HLINEAPP hLineApp, DWORD dwDeviceID, LPHLINE lphLine, DWORD dwAPIVersion, DWORD dwExtVersion, DWORD dwCallbackInstance, DWORD dwPrivileges, DWORD dwMediaModes, LPLINECALLPARAMS const lpCallParams);

Parameters

hLineApp

[in] Handle to the application's registration with TAPI.

dwDeviceID

[in] Species the identifier of the line device to be opened. It must be a valid device identifier.

lphLine

[out] Pointer to an HLINE handle that 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

[in] Specifies the TAPI version number under which the application and TAPI have agreed to operate. This number is obtained with lineNegotiateAPIVersion.

dwExtVersion

[in] Unsupported; set to zero.

dwCallbackInstance

[in] Specifies user-instance data passed back to the application with each message associated with this line or with addresses or calls on this line. This parameter is not interpreted by TAPI.

dwPrivileges

[in] Specifies the privilege the application wants for the calls it is notified for. This parameter can be a combination of the LINECALLPRIVILEGE_* constants.

Value	Description
LINECALLPRIVILEGE_NONE	The application can make only outgoing calls.
LINECALLPRIVILEGE_MONITOR	The application can monitor only incoming and outgoing calls.
LINECALLPRIVILEGE_OWNER	The application can own only incoming calls of the types specified in dwMediaModes.
LINECALLPRIVILEGE_MONITOR + LINECALLPRIVILEGE_OWNER	The application can own only incoming calls of the types specified in dwMediaModes, but if it is not an owner of a call, it is a monitor.

Other flag combinations are invalid.

dwMediaModes

[in] Specifies the media mode or modes of interest to the application. This parameter is used to register the application as a potential target for incoming 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:

Value	Description
LINEMEDIAMODE_UNKNOWN	The application can handle calls of unknown media type (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE	The application can 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 can handle calls with the data-modem media mode.
LINEMEDIAMODE_G3FAX	The application can handle calls of the group 3 fax media type.
LINEMEDIAMODE_TDD	The application can handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX	The application can handle calls of the group 4 fax media type.
LINEMEDIAMODE_DIGITALDATA	The application can handle calls of the digital-data media type.
LINEMEDIAMODE_TELETEX	The application can handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX	The application can handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX	The application can handle calls with the telex media mode.
LINEMEDIAMODE_MIXED	The application can handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI	The application can handle calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW	The media mode of the call is VoiceView.

lpCallParams

[in] Pointer to a structure of type LINECALLPARAMS. This pointer should be set to NULL for Windows CE 2.x.

Return Values

Zero indicates success. A negative error number indicates that an error occurred. Possible error values are as follows:

LINEERR_ALLOCATED	LINEERR_NODEVICE
LINEERR_BADDEVICEID	LINEERR_NODRIVER
LINEERR_INCOMPATIBLEAPIVERSION	LINEERR_NOMEM
LINEERR_INCOMPATIBLEEXTVERSION	LINEERR_OPERATIONFAILED
LINEERR_INVALAPPHANDLE	LINEERR_OPERATIONUNAVAIL
LINEERR_INVALMEDIAMODE	LINEERR_REINIT
LINEERR_INVALPOINTER	LINEERR_RESOURCEUNAVAIL
LINEERR_INVALPRIVSELECT	LINEERR_STRUCTURETOOSMALL
LINEERR_LINEMAPPERFAILED	LINEERR_UNINITIALIZED

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 can be transitory, caused by monitoring of media mode or tones, and changes in these activities by other applications can 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 that time the new configuration becomes effective and applications are once again permitted to call lineInitialize.

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 incoming 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 outgoing 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 incoming call type determination. 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 initiate calls using lineMakeCall.

A single application can specify multiple flags simultaneously to handle multiple media modes. Conflicts can 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 incoming call first arrives or when a call is handed off.

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 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, and would be dropped.

The same application, or different installations of the same application, can open the same line multiple times with the same or different parameters.

When an application opens a line device it must specify the negotiated TAPI version, which is obtained with a call to lineNegotiateAPIVersion. Version numbering enables the mixing and matching of different application versions with different TAPI versions.