Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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.

Syntax 

LONG lineMakeCall(
  HLINE 
hLine, 
  LPHCALL 
lphCall, 
  LPCWSTR 
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_REPLYmessage is received by the application indicating that the lineMakeCallfunction 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/region code of the called party. If a value of 0 is specified, a default is used by the implementation.

lpCallParams

[in] Pointer to a LINECALLPARAMSstructure. 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 Value

A positive request identifier indicates that the function is completed asynchronously. A negative error number indicates that an error has occurred. The dwParam2parameter 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 address is blocked

LINEERR_BEARERMODEUNAVAIL

The bearer mode member in LINECALLPARAMSis invalid, the bearer mode specified in LINECALLPARAMSis not available, or the call's bearer mode cannot be changed to the specified bearer mode.

LINEERR_CALLUNAVAIL

The call is unavailable.

LINEERR_DIALBILLING

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

LINEERR_DIALDIALTONE

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

LINEERR_DIALPROMPT

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

LINEERR_DIALQUIET

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

LINEERR_INUSE

The line is in use.

LINEERR_INVALADDRESS

The address is invalid.

LINEERR_INVALADDRESSID

The address id is invalid.

LINEERR_INVALADDRESSMODE

The address mode is invalid.

LINEERR_INVALBEARERMODE

The bearer mode is invalid.

LINEERR_INVALCALLPARAMS

Invalid parameters used for this call.

LINEERR_INVALCOUNTRYCODE

The country/region code provided was invalid.

LINEERR_INVALLINEHANDLE

The line handle is invalid.

LINEERR_INVALLINESTATE

The line is not in a state such that this operation can be performed.

LINEERR_INVALMEDIAMODE

The media mode is invalid.

LINEERR_INVALPARAM

The parameters are invalid.

LINEERR_INVALPOINTER

The pointer is invalid.

LINEERR_INVALRATE

The rate is invalid.

LINEERR_NOMEM

The operation requires more memory than is currently available.

LINEERR_OPERATIONFAILED

The operation failed.

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:

Some cellular carriers provide equivalent functionality through the flash feature, which with TAPI 2.2 can be accessed with the lineGenerateDigitsfunction. 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_RATEUNAVAIL

The rate is unavailable.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_STRUCTURETOOSMALL

The structure is too small.

LINEERR_UNINITIALIZED

The parameter is uninitialized.

LINEERR_USERUSERINFOTOOBIG

The users information is too large.

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 dwLineFeaturesmember (of the type LINEFEATURE_) in the LINEDEVSTATUSstructure. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineMakeCallhave 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_CALLSTATEmessages 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 connectedstate.

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 lineMakeCalland continue dialing using the lineDialfunction. To abandon a call attempt, use the lineDropfunction.

After lineMakeCallreturns 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.

Requirements

Header tapi.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also