Share via


TSPI_lineDial (Compact 2013)

3/26/2014

This function dials the specified dialable number on the specified call.

Syntax

LONG TSPIAPI TSPI_lineDial(
  DRV_REQUESTID dwRequestID,  
  HDRVCALL hdCall,  
  LPCWSTR lpszDestAddress,  
  DWORD dwCountryCode 
);

Parameters

  • dwRequestID
    Identifier of the asynchronous request.
  • hdCall
    Service provider's handle to the call to be dialed. The call state of hdCall can be any state except idle and disconnected.
  • lpszDestAddress
    Pointer to a null-terminated Unicode string that specifies the destination to be dialed using the standard dialable number format.
  • dwCountryCode
    The country/region code of the destination. The implementation uses this to select the call progress protocols for the destination address. If a value of zero is specified, a default call-progress protocol defined by the service provider is used. TAPI does not validate this parameter when this function is called.

Return Value

Returns dwRequestID or an error number if an error occurs. The lResultactual parameter of the corresponding ASYNC_COMPLETION is 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_INVALCALLHANDLE

The handle to the call is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALADDRESS

The address is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_INVALCOUNTRYCODE

The country/region code is invalid.

LINEERR_DIALBILLING

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_INVALCALLSTATE

The call state is invalid.

LINEERR_DIALQUIET

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_ADDRESSBLOCKED

The address is blocked.

LINEERR_DIALDIALTONE

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_DIALPROMPT

The dialable address parameter contains dialing control characters that are not processed by the service provider.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow dialing.

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

If the service provider returns LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT, it should perform none of the actions otherwise performed by TSPI_lineDial (for example, no partial dialing, and no going offhook). This is because the service provider should pre-scan the number for unsupported characters first.

TSPI_lineDial is used for dialing on an existing call appearance; for example, call handles returned from the TSPI_lineMakeCall function with NULL as the lpszDestAddress or ending in ';', call handles returned from the TSPI_lineSetupTransferfunction**,** or the TSPI_lineSetupConferencefunction. TSPI_lineDial can be invoked multiple times in the course of dialing in the case of multistage dialing, if the line's device capabilities permit it.

If the string, pointed to by the lpszDestAddress parameter in the previous call to the TSPI_lineMakeCall or TSPI_lineDial function, is terminated with a semicolon, an empty string in the current call to TSPI_lineDial indicates that dialing is complete.

Multiple addresses can be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses, and return a single call handle to the aggregate of all calls to the application. All addresses would use the same country/region code.

Dialing is considered complete after the address has been accepted by the service provider, not after the call is finally connected. Service providers that provide inverse multiplexing may allow multiple addresses to be provided at once. The service provider must send LINE_CALLSTATE messages to TAPI to inform it about the progress of the call.

Requirements

Header

tspi.h

Library

CellTSP.dll

See Also

Reference

TSPI Line Device Functions
TSPI_lineMakeCall