función TSPI_lineMonitorTones (tspi.h)

Artículo
03/09/2024

La función TSPI_lineMonitorTones habilita y deshabilita la detección de tonos de banda en la llamada. Cada vez que se detecta un tono especificado, se envía un mensaje a la aplicación cliente a través de TAPI.

Sintaxis

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

Parámetros

hdCall

Identificador de la llamada para la que se va a realizar la detección de tono. El estado de llamada de hdCall puede ser cualquier estado excepto inactivo.

dwToneListID

Identificador único de esta lista de tonos. Varias listas de tonos pueden ser pendientes a la vez. El proveedor de servicios debe reemplazar cualquier lista antigua que tenga el mismo dwToneListID por la nueva lista de tonos. Si lpToneList es NULL, la lista de tonos con dwToneListID simplemente se quita. En cualquier caso, otras listas de tonos con dwToneListIDdiferentes se mantienen sin cambios.

lpToneList

Lista de tonos que se van a supervisar, de tipo LINEMONITORTONE. Cada tono de esta lista tiene un campo de etiqueta definido por la aplicación que se usa para identificar tonos individuales en la lista con el fin de notificar una detección de tono. La supervisión de tonos en curso se cancela o cambia llamando a esta operación con NULL para lpToneList o con otra lista de tonos. El proveedor de servicios debe copiar la lista de tonos en su propia memoria para referencia posterior, en lugar de simplemente conservar el puntero en la memoria de la aplicación.

dwNumEntries

Número de entradas en lpToneList. El parámetro dwNumEntries se omite si lpToneList es NULL. TAPI no valida este parámetro cuando se llama a esta función.

Valor devuelto

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

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Comentarios

Esta función devuelve cero (correcto) cuando se inicia correctamente la supervisión del tono, no cuando finaliza la supervisión de tono. Al igual que con la supervisión multimedia, la supervisión de tono permanece en vigor para una lista de tonos determinada hasta que esa lista de tonos se deshabilita explícitamente llamando a TSPI_lineMonitorTones con el mismo dwToneListID y otra lista de tonos (o una lista de tonos NULL ), o hasta que la llamada pasa a inactiva.

Aunque esta función se puede invocar en cualquier estado de llamada excepto inactivo, los tonos normalmente solo se pueden detectar mientras la llamada está en estado conectado . La detección de tonos normalmente requiere recursos computacionales. Según el proveedor de servicios y otras actividades que compiten por estos recursos, el número de tonos que se pueden detectar puede variar con el tiempo. Además, se puede consumir una cantidad equivalente de recursos para supervisar un único tono de frecuencia triple frente a tres tonos de frecuencia única. Si se sobremiten los recursos, el proveedor de servicios devuelve LINEERR_RESOURCEUNAVAIL.

El proveedor de servicios supervisa todos los tonos de todas las listas de tonos simultáneamente. Cuando se detecta un tono, cada tono coincidente de cada lista de tonos se notifica por separado mediante un mensaje de LINE_MONITORTONE . Cada informe de tono incluye el identificador de lista de tonos y la etiqueta específica de la aplicación. Es posible que algunos proveedores de servicios no puedan discriminar tonos muy cercanos, por lo que es posible que se notifiquen varias coincidencias incluso para tonos cuyas descripciones no sean estrictamente idénticas.

NotaTSPI_lineMonitorTones también se usa para detectar silencio. El silencio se especifica como un tono con todas las frecuencias cero.

La función correspondiente en el nivel TAPI no incluye un parámetro dwToneListID . La inclusión de este parámetro en la interfaz TSPI permite a TAPI reenviar la unión de todas las listas de supervisión de tono de todas las aplicaciones al proveedor de servicios, a la vez que conserva la capacidad de filtrar y reenviar los eventos de detección de tono según la aplicación. Esto proporciona a los diseñadores de proveedores de servicios la máxima flexibilidad para determinar el grado en que pueden discriminar tonos muy cercanos, ya que TAPI no supone qué descripciones de tono se consideran idénticas.