TSPI_lineSetMediaControl

The TSPI_lineSetMediaControl function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states. The new specified media controls replace all the ones that were in effect for this line, address, or call prior to this request.

LONG TSPI_lineSetMediaControl(
  HDRVLINE hdLine,                                    
  DWORD dwAddressID,                                  
  HDRVCALL hdCall,                                    
  DWORD dwSelect,                                     
  LPLINEMEDIACONTROLDIGIT const lpDigitList,          
  DWORD dwDigitNumEntries,                            
  LPLINEMEDIACONTROLMEDIA const lpMediaList,          
  DWORD dwMediaNumEntries,                            
  LPLINEMEDIACONTROLTONE const lpToneList,            
  DWORD dwToneNumEntries,                             
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,  
  DWORD dwCallStateNumEntries                         
);
 

Parameters

hdLine

The handle to a line.

dwAddressID

An address on the given open line device. TAPI does not validate this parameter when this function is called.

hdCall

The handle to a call. The call state of hdCall can be any state.

dwSelect

Specifies whether media control is requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This parameter uses the following LINECALLSELECT_ constants:

LINECALLSELECT_LINE

Select the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID must be ignored.

LINECALLSELECT_ADDRESS

Select the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall must be ignored.

LINECALLSELECT_CALL

Select the specified call. hdCall must be valid; hdLine and dwAddressID must be ignored.

lpDigitList

A pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit listed in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries

The number of entries in the lpDigitList. TAPI does not validate this parameter when this function is called.

lpMediaList

A pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media mode to be monitored, media-type specific information (such as duration), and a media control field. If a media mode in the list is detected, the corresponding media control action is performed on the call's media stream.

dwMediaNumEntries

The number of entries in lpMediaList. TAPI does not validate this parameter when this function is called.

lpToneList

A pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media control field. If a tone in the list is detected, the corresponding media control action is performed on the call's media stream.

dwToneNumEntries

The number of entries in lpToneList. TAPI does not validate this parameter when this function is called.

lpCallStateList

A pointer to an array with entries of type LINEMEDIACONTROLCALLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action.

dwCallStateNumEntries

The number of entries in lpCallStateList. TAPI does not validate this parameter when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALADDRESSID, LINEERR_INVALPOINTER, LINEERR_INVALCALLHANDLE, LINEERR_INVALTONELIST, LINEERR_INVALCALLSELECT, LINEERR_NOMEM, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITLIST, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIALIST.

Remarks

This function returns zero (success) when media control is correctly initiated, not when any media control takes effect. Media control in progress is changed or is canceled when this function is called again with either different parameters or NULLs.

Only a single media control request can be outstanding on a call at one time. A request replaces any that may be outstanding.

Depending on the service provider and other activities that compete for such resources, the amount of simultaneous detections that can be made can vary over time. If service provider resources are overcommitted, it returns LINEERR_RESOURCEUNAVAIL.

Whether or not media control is supported by the service provider is a device capability indicated in LINEDEVCAPS.

Each time TSPI_lineSetMediaControl is called, the new request overrides any media control currently in effect. If one or more of the parameters lpDigitList, lpMediaList, lpToneList, and lpCallStateList are NULL, the corresponding digit, media mode, tone, or call state-triggered media control is disabled. To modify just a portion of the media control parameters while leaving the remaining settings in effect, the application should invoke TSPI_lineSetMediaControl supplying the previous parameters for those potions that must remain in effect, and new parameters for those parts that are to be modified.

See Also

LINEDEVCAPS, LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE, LINEDIGITMODE_ Constants, LINEMEDIAMODE_ Constants, TSPI_lineGetDevCaps