función TSPI_lineSetMediaControl (tspi.h)

Artículo
03/13/2024

La función TSPI_lineSetMediaControl habilita y deshabilita las acciones de control en el flujo multimedia asociado a la línea, dirección o llamada especificadas. Las acciones de control multimedia se pueden desencadenar mediante la detección de dígitos, tipos de medios, tonos personalizados y estados de llamada especificados. Los nuevos controles multimedia especificados reemplazan a todos los que estaban en vigor para esta línea, dirección o llamada antes de esta solicitud.

Sintaxis

LONG TSPIAPI 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
);

Parámetros

hdLine

Identificador de una línea.

dwAddressID

Una dirección en el dispositivo de línea abierta especificado. Un identificador de dirección está asociado permanentemente a una dirección; el identificador permanece constante en las actualizaciones del sistema operativo. TAPI no valida este parámetro cuando se llama a esta función.

hdCall

Identificador de una llamada. El estado de llamada de hdCall puede ser cualquier estado.

dwSelect

Especifica si el control multimedia se solicita está asociado a una sola llamada, es el valor predeterminado para todas las llamadas de una dirección o es el valor predeterminado para todas las llamadas de una línea. Este parámetro usa las siguientes constantes de LINECALLSELECT_.

lpDigitList

Puntero a la matriz que contiene los dígitos que se van a desencadenar acciones de control multimedia, de tipo LINEMEDIACONTROLDIGIT. Cada vez que se detecta un dígito que aparece en la lista de dígitos, la acción de control de medios especificada se lleva a cabo en la secuencia multimedia de la llamada.

Los dígitos válidos para el modo de pulso son "0" a "9". Los dígitos válidos para el modo DTMF son "0" a "9", "A", "B", "C", "D", "*", "#".

dwDigitNumEntries

Número de entradas en lpDigitList. TAPI no valida este parámetro cuando se llama a esta función.

lpMediaList

Puntero a una matriz con entradas de tipo LINEMEDIACONTROLMEDIA. La matriz tiene entradas dwMediaNumEntries . Cada entrada contiene un tipo de medio que se va a supervisar, información específica del tipo multimedia (por ejemplo, duración) y un campo de control multimedia. Si se detecta un tipo de medio en la lista, la acción de control multimedia correspondiente se realiza en la secuencia multimedia de la llamada.

dwMediaNumEntries

Número de entradas en lpMediaList. TAPI no valida este parámetro cuando se llama a esta función.

lpToneList

Puntero a una matriz con entradas de tipo LINEMEDIACONTROLTONE. La matriz tiene entradas dwToneNumEntries . Cada entrada contiene una descripción de un tono que se va a supervisar, la duración del tono y un campo de control multimedia. Si se detecta un tono en la lista, la acción de control multimedia correspondiente se realiza en la secuencia multimedia de la llamada.

dwToneNumEntries

Número de entradas en lpToneList. TAPI no valida este parámetro cuando se llama a esta función.

lpCallStateList

Puntero a una matriz con entradas de tipo LINEMEDIACONTROLCALLSTATE. La matriz tiene entradas dwCallStateNumEntries . Cada entrada contiene un estado de llamada y una acción de control multimedia.

dwCallStateNumEntries

Número de entradas en lpCallStateList. TAPI no valida este parámetro cuando se llama a esta función.

Valor devuelto

Devuelve cero si la función se realiza correctamente o un número de error si se produce un error. Los valores devueltos posibles son los siguientes:

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.

Comentarios

Esta función devuelve cero (correcto) cuando se inicia correctamente el control multimedia, no cuando se aplica ningún control multimedia. El control multimedia en curso se cambia o se cancela cuando se llama a esta función de nuevo con parámetros diferentes o valores NULL.

Solo una única solicitud de control multimedia puede estar pendiente en una llamada a la vez. Una solicitud reemplaza a cualquier que pueda estar pendiente.

Según el proveedor de servicios y otras actividades que compiten por estos recursos, la cantidad de detecciones simultáneas que se pueden realizar puede variar con el tiempo. Si se sobrecommiten los recursos del proveedor de servicios, devuelve LINEERR_RESOURCEUNAVAIL.

Si el proveedor de servicios admite o no el control multimedia es una funcionalidad del dispositivo indicada en LINEDEVCAPS.

Cada vez que se llama a TSPI_lineSetMediaControl , la nueva solicitud invalida cualquier control multimedia actualmente en vigor. Si uno o varios de los parámetros lpDigitList, lpMediaList, lpToneList y lpCallStateList son NULL, se deshabilita el dígito correspondiente, el tipo de medio, el tono o el control multimedia desencadenado por estado de llamada. Para modificar solo una parte de los parámetros de control multimedia y dejar la configuración restante en vigor, la aplicación debe invocar TSPI_lineSetMediaControl proporcionar los parámetros anteriores para esas partes que deben permanecer en vigor y nuevos parámetros para esas partes que se van a modificar.