TSPI_lineCompleteCall

The TSPI_lineCompleteCall function is used to specify how a call that cannot be connected normally is to be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer.

LONG TSPI_lineCompleteCall(
  DRV_REQUESTID dwRequestID,  
  HDRVCALL hdCall,         
  LPDWORD lpdwCompletionID,  
  DWORD dwCompletionMode,  
  DWORD dwMessageID        
);
 

Parameters

dwRequestID

The identifier of the asynchronous request.

hdCall

The service provider's handle to the call whose completion is requested. The call state of hdCall can be busy, ringback, or proceeding.

lpdwCompletionID

A pointer to a DWORD-sized memory location where the service provider writes a completion identifer. This uniquely identifies a completion request in progress on the line that contains the hdCall. In particular, a completion identifier becomes invalid after the request completes or is canceled using the TSPI_lineUncompleteCall function. The service provider is free to reuse the completion identifier as soon as it becomes invalid.

dwCompletionMode

The way in which the call is to be completed. This parameter uses the following LINECALLCOMPLMODE_ constants. Only one of the indicated flags can be set at a time:

LINECALLCOMPLMODE_CAMPON

Queue the call until the call can be completed. The call remains in the busy state while queued.

LINECALLCOMPLMODE_CALLBACK

Request the called station to return the call when the called station becomes idle. The call typically transitions to the idle state.

LINECALLCOMPLMODE_INTRUDE

Request that the call be added to an existing physical call at the called station (barge in). The call typically transitions to the connected state when the intrusion occurs.

LINECALLCOMPLMODE_MESSAGE

Leave a short predefined message for the called station (Leave Word Calling). The message to be sent is specified in dwMessageID. The call typically transitions to the idle state.

dwMessageID

The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This identifier selects the message from a small number of predefined messages. This parameter is not validated by TAPI when this function is called.

Return Values

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. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLCOMPLMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_COMPLETIONOVERRUN, LINEERR_INVALMESSAGEID.

Remarks

This function is considered complete when the request is accepted by the network or switch; not when the request is fully completed in the way specified. When the called station or network enters a state where the call can be completed as requested, the service privider must send a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provides the completion identifier as well. It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion identifier is also used to refer to each individual request so requests can be canceled by calling TSPI_lineUncompleteCall.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINECALLINFO, LINECALLCOMPLMODE_ Constants, LINECALLSTATUS, TSPI_lineGetCallInfo, TSPI_lineUncompleteCall