lineDial (Compact 2013)

3/26/2014

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

Syntax

LONG WINAPI lineDial(
  HCALL hCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode 
);

Parameters

• hCall
  Handle to the call on which a number is to be dialed. The application must be an owner of the call. The call state of hCall can be any state except idle and disconnected.

• lpszDestAddress
  Destination to be dialed using the standard dialable number format.

• dwCountryCode
  Country/region code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of zero is specified, a service provider-defined default call progress protocol is used.

Return Value

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. The following table shows the return values for this function.

Value	Description
LINEERR_ADDRESSBLOCKED	The destination address is blocked.
LINEERR_INVALPOINTER	The pointer is invalid.
LINEERR_DIALBILLING	The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_NOMEM	Not enough memory is available.
LINEERR_DIALDIALTONE	The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_NOTOWNER	The application is not the owner of this call.
LINEERR_DIALPROMPT	The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_OPERATIONFAILED	The operation failed.
LINEERR_DIALQUIET	The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_OPERATIONUNAVAIL	The operation is unavailable. With code division multiple access (CDMA), this function will fail if a call is currently in progress. CDMA does not provide the necessary functionality to support the following TAPI functions: lineAccept lineAnswer lineClose lineCompleteTransfer lineDial lineDrop lineHold lineMakeCall linePark linePickup lineSwapHold Some cellular carriers provide equivalent functionality through the flash feature, which with TAPI 2.2 can be accessed with the lineGenerateDigits function. Because the exact flash sequences are controlled by the cellular providers, the application must be completely aware of the necessary codes implemented by the cellular providers.
LINEERR_INVALCALLHANDLE	The handle to the call is invalid.
LINEERR_RESOURCEUNAVAIL	The resources are unavailable.
LINEERR_INVALCALLSTATE	The call state of hCall is either idle or disconnected.
LINEERR_UNINITIALIZED	A parameter is uninitialized.
LINEERR_INVALCOUNTRYCODE	The destination country/region code is invalid.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing has been done. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineDial have occurred. For example, none of the dialable addresses prior to the offending character has been dialed, no hookswitch state has changed, and so on.

The lineDial function is used for dialing on an existing call appearance. For example, after a call has been set up for transfer or conference, a consultation call is automatically allocated, and the lineDial function would be used to perform the dialing of this consultation call. The lineDial function can be invoked multiple times in the course of multistage dialing, if the line's device capabilities allow it. Also, 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 can 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 passed to the service provider; not after the call is finally connected. Service providers that provide inverse multiplexing can allow multiple addresses to be provided at once. The service provider sends LINE_CALLSTATE messages to the application to inform it about the progress of the call. To abort a call attempt while a call is being established, the invoking application should use the lineDrop function.

An application can set the lpszDestAddress parameter of the lineDial function to the address of an empty string to indicate that dialing is complete, but only if the previous calls to the lineMakeCall and lineDial functions have had the strings specified by lpszDestAddress terminated with semicolons.

Requirements

Header	tapi.h
Library	TAPI32.dll

See Also

Reference

TAPI Line Device Functions
lineDrop
lineMakeCall
LINE_CALLSTATE (TAPI)
LINE_REPLY