lineMakeCall

This function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.  

At a Glance

Syntax

LONG lineMakeCall(HLINE hLine, LPHCALL lphCall,
LPCTSTR lpszDestAddress, DWORD dwCountryCode,
LPLINECALLPARAMS const lpCallParams);

Parameters

hLine

[in] Handle to the open line device on which a call is to be originated.

lphCall

[in] Pointer to an HCALL handle. The handle is only valid after the LINE_REPLY message is received by the application indicating that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application is initially the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously by the reply message).

lpszDestAddress

[in] Pointer to the null-terminated string that contains the destination address. This follows the standard dialable number format. This pointer can be NULL for non-dialed addresses (as with a hot phone). Service providers that have inverse multiplexing capabilities can enable an application to specify multiple addresses at once.

dwCountryCode

[in] Specifies the country code of the called party. If a value of 0 is specified, a default is used by the implementation.

lpCallParams

[in] Pointer to a LINECALLPARAMS structure. This structure enables the application to specify how it wants the call to be set up. If NULL is specified, a default 3.1 kHz voice call is established and an arbitrary origination address on the line is selected. This structure enables the application to select elements such as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller identification data, and dialing parameters.

Return Values

A positive request identifier indicates that the function is completed asynchronously. A negative error number indicates that an error has occurred. 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. Possible error values are as follows:

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE_) in the LINEDEVSTATUS structure. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineMakeCall have occurred; for example, none of the dialable address prior to the offending character has been dialed, no hook switch state has changed, and so on.

After dialing has completed, several LINE_CALLSTATE messages are usually sent to the application to notify it about the progress of the call. No generally valid sequence of call-state transitions is specified, as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence can cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call can typically transition directly to connected state.

An application has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device enables the application to originate calls from any of these stations using lineMakeCall.

The call parameters enable the application to make non-voice calls or request special call setup options that are not available by default.

An application can partially dial using lineMakeCall and continue dialing using lineDial. To abandon a call attempt, use lineDrop.

After lineMakeCall returns a success reply message to the application, a LINE_CALLSTATE message is sent to the application to indicate the current state of the call. This state is not necessarily LINECALLSTATE_DIALTONE.

For Windows CE versions 1.0 through 2.11, lineMakeCall does not handle timeouts correctly. If a connection fails after lineMakeCall returns but before the associated LINE_REPLY message is received, a LINE_REPLY message is not generated. Because a LINE_REPLY message is never received, an application does not have the handle for the call. Without a handle, an application cannot call lineDrop nor lineDeallocateCall free call resources. Because call resources are never deallocated, a call fails that is placed on the line before it is closed.

For Windows CE versions 2.12 and later, the timeout problem is addressed by UNIMODEM sending a LINEMAKECALL_TIMEOUT message after eight seconds without a response.

See Also

LINECALLPARAMS