TSPI_lineDial

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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 lResult actual 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.

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

See Also

Reference

TSPI_lineMakeCall