TSPI_lineDial

  • Article

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

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 Values

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.

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_lineSetupTransfer function**,** or the TSPI_lineSetupConference function. 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

OS Versions: Windows CE 3.0 and later.
Header: Tapicomn.h.
Link Library: Coredll.lib.

See Also

TSPI_lineMakeCall

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.