Share via


TSPI_lineMakeCall (Compact 2013)

3/26/2014

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 TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID dwRequestID, 
  HDRVLINE hdLine, 
  HTAPICALL htCall, 
  LPHDRVCALL lphdCall, 
  LPCWSTR lpszDestAddress, 
  DWORD dwCountryCode, 
  LPLINECALLPARAMS const lpCallParams 
);

Parameters

  • dwRequestID
    Identifier of the asynchronous request.
  • hdLine
    Handle to the line on which the new call is to be originated.
  • htCall
    TAPI handle to the new call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
  • lphdCall
    Pointer to a call handle. The service provider must fill this location with its handle for the call before this procedure returns. This handle is ignored by TAPI if the function results in an error.
  • lpszDestAddress
    Pointer to a null-terminated Unicode string that specifies the destination address. This follows the standard dialable number format. This pointer can be specified as NULL for non-dialed addresses (as with a hot phone, which always automatically connects to a predefined number) or when all dialing is performed using the TSPI_lineDial function. In the latter case, TSPI_lineMakeCall allocates an available call appearance that would typically remain in the dial tone state until dialing begins. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.
  • dwCountryCode
    Country/region code of the called party. If a value of zero is specified, a default is used by the implementation.
  • lpCallParams
    A pointer to a LINECALLPARAMS structure. This structure allows TAPI to specify how it wants the call to be set up. If NULL is specified, a default 3.1kHz voice call is established, and an arbitrary origination address on the line is selected. This structure selects elements such as the call's bearer mode, data rate, expected media type, origination address, blocking of caller ID information, and dialing parameters.

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.

Value

Description

LINEERR_ADDRESSBLOCKED

The address is blocked.

LINEERR_INVALLINESTATE

The line state is invalid.

LINEERR_BEARERMODEUNAVAIL

The bearer mode is unavailable.

LINEERR_INVALRATE

The rate is invalid.

LINEERR_CALLUNAVAIL

The call is unavailable.

LINEERR_INVALLINEHANDLE

The handle to the line is invalid.

LINEERR_DIALBILLING

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

LINEERR_INVALADDRESS

The address is invalid.

LINEERR_DIALQUIET

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

LINEERR_INVALADDRESSID

The address id is invalid.

LINEERR_DIALDIALTONE

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

LINEERR_INVALCALLPARAMS

The call parameters are invalid.

LINEERR_DIALPROMPT

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

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INUSE

The line is in use.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALADDRESSMODE

The address mode is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALBEARERMODE

The bearer mode is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_INVALCOUNTRYCODE

The country/region code is invalid.

LINEERR_RATEUNAVAIL

The rate is unavailable.

LINEERR_INVALMEDIAMODE

The media mode is invalid.

LINEERR_USERUSERINFOTOOBIG

The user user information is too big.

Remarks

The service provider returns LINEERR_INVALLINESTATE if 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 LINEDEVSTATUS structure. (Calling the TSPI_lineGetLineDevStatus function updates the information in LINEDEVSTATUS.)

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_lineMakeCall. For example, no partial dialing, and no going offhook. This is because the service provider should pre-scan the number for unsupported characters first.

After TSPI_lineMakeCall returns a SUCCESS reply callback message to the application, the service provider must send LINE_CALLSTATE messages to the lpfnEventProc passed in TSPI_lineOpen to notify TAPI about the progress of the call. A typical reported sequence may be dial tone, dialing, proceeding, ringback, and connected; The first state reported is not necessarily LINECALLSTATE_DIALTONE. The service provider chooses how many of these states are reported. It is recommended that as many as possible are sent, so that applications can take appropriate actions.

The service provider initially does media monitoring on the new call for at least the set of media types that were monitored for on the line.

If the dial string is NULL, the service provider takes the line to the dial tone state (for a COMM-based service provider, this would involve ATD) and send a call-state message indicating LINECALLSTATE_DIALTONE.

If the dial string ends in ';' (a semicolon), the service provider dials the partial number and sends the LINECALLSTATE_DIALING message. This call is completed by calls to the TSPI_lineDial function.

If the dial string contains characters (W, @, $, ?) that are not supported by the service provider, the service provider must scan the dial string and return (synchronously) an error corresponding to the first invalid character.

If the LINECALLPARAMFLAGS_IDLE flag is set, the service provider must check the current line status (the equivalent of going off-hook and sensing dial tone). If this IDLE flag is set and there is no dial tone, the function fails with the error LINEERR_CALLUNAVAIL. If the IDLE flag is not set, or there is a dial tone, the dialing can continue.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION function reports success. It must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Header

tspi.h

Library

TAPI32.dll

See Also

Reference

TSPI Line Device Functions
LINEEVENT
TSPI_lineDial
TSPI_lineDrop