Partager via

TSPI_lineOpen (Compact 2013)

  • Article

3/26/2014

This function opens the line device whose device identifier is given, returning the service provider's handle for the device. The service provider must retain the TAPI handle for the device for use in subsequent calls to the LINEEVENT callback procedure.

Syntax

LONG TSPIAPI TSPI_lineOpen(
  DWORD dwDeviceID, 
  HTAPILINE htLine, 
  LPHDRVLINE lphdLine, 
  DWORD dwTSPIVersion, 
  LINEEVENT lpfnEventProc 
);

Parameters

  • dwDeviceID
    Line device to be opened.
  • htLine
    TAPI handle for the line device to be used in subsequent calls to the LINEEVENT callback procedure to identify the device.
  • lphdLine
    Pointer to an HDRVLINE where the service provider fills in its handle for the line device.
  • dwTSPIVersion
    TSPI version.
  • lpfnEventProc
    Pointer to the LINEEVENT callback procedure supplied by TAPI that the service provider calls to report subsequent events on the line.

Return Value

Returns zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this function.

Value

Description

LINEERR_ALLOCATED

The line cannot be opened due to a persistent condition, such as that of a serial port being exclusively opened by another process.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_NODRIVER

The driver cannot be found.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

Remarks

The service provider should reserve any non-sharable resources that are required to manage the line. However, any actions that can be postponed to the lineMakeCall function should be. It is a design assumption in TAPI that lineOpen is an "inexpensive" operation. For example, if the line is opened in monitor mode only, it should not be necessary for a COMM-port-based service provider to open the COMM port.

This procedure does not correspond directly to any procedure at the TAPI level, at which the functions that enable device-specific extensions, select line characteristics, and set media type detection are included in the functionality defined by lineOpen. At the TSPI level, these additional capabilities are separated out into the TSPI_lineNegotiateExtVersion, TSPI_lineSetDefaultMediaDetection and TSPI_lineConditionalMediaDetection functions.

Requirements

Header

tspi.h

Library

CellTSP.dll

See Also

Reference

TSPI Line Device Functions
LINEEVENT
TSPI_lineClose
TSPI_lineConditionalMediaDetection
TSPI_lineNegotiateExtVersion
TSPI_lineNegotiateTSPIVersion
TSPI_lineSetDefaultMediaDetection