Función lineSetMediaControl (tapi.h)

Artículo
03/08/2023

La función 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.

Sintaxis

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Parámetros

hLine

Identificador de un dispositivo de línea abierta.

dwAddressID

Identificador de 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.

hCall

Identificador de una llamada. La aplicación debe ser propietario de la llamada. El estado de llamada de hCall puede ser cualquier estado.

dwSelect

Si el control multimedia solicitado 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 es uno y solo uno de los LINECALLSELECT_ Constantes.

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 en la lista de dígitos, la acción de control multimedia 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.

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.

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.

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. Cada vez que la llamada especificada pasa a uno de los estados de llamada de la lista, se invoca la acción de control multimedia correspondiente.

dwCallStateNumEntries

Número de entradas en lpCallStateList.

Valor devuelto

Devuelve cero si la solicitud se realiza correctamente o un número de error negativo si se produce un error. Los valores devueltos posibles son:

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

Comentarios

La función lineSetMediaControl se considera correcta si el control multimedia se ha iniciado correctamente, no cuando se ha producido ningún control multimedia. El control multimedia en curso se cambia o se cancela llamando a esta función de nuevo con parámetros diferentes o valores NULL. Si uno o varios de los parámetros lpDigitList, lpMediaList, lpToneList y lpCallStateList son NULL, se deshabilita el dígito correspondiente, tipo de medio, tono o control multimedia desencadenado por estado de llamada. Para modificar solo una parte de los parámetros de control multimedia mientras deja la configuración restante en vigor, la aplicación debe invocar lineSetMediaControl, proporcionando los parámetros anteriores para esas partes que deben permanecer en vigor y nuevos parámetros para esas partes que se van a modificar.

Si se selecciona hCall y la llamada finaliza o la aplicación desasigna su identificador, se cancela el control multimedia en esa llamada.

Todas las aplicaciones que son propietarios de la llamada están en principio permitidas para realizar solicitudes de control multimedia en la llamada. Solo una única solicitud de control multimedia puede estar pendiente en una llamada en todas las aplicaciones que poseen la llamada. Cada vez que se llama a lineSetMediaControl , la nueva solicitud invalida cualquier control multimedia y, a continuación, en vigor en la llamada, ya sea establecido por la aplicación que realiza la llamada o por cualquier otra aplicación propietaria.

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

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