TSPI_lineMakeCall
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 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 | tapicomn.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |