función TSPI_lineGenerateTone (tspi.h)

Artículo
08/26/2023

La función TSPI_lineGenerateTone genera el tono especificado en banda a través de la llamada especificada. Al invocar esta función con un cero para dwToneMode , se anula cualquier generación de tono que esté en curso en la llamada especificada. Invocar TSPI_lineGenerateTone o TSPI_lineGenerateDigits mientras la generación de tonos está en curso anula la generación de tonos actual o la generación de dígitos en curso e inicia la generación del tono o dígitos recién especificados.

Sintaxis

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL                 hdCall,
  DWORD                    dwEndToEndID,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parámetros

hdCall

Identificador del proveedor de servicios a la llamada en la que se va a realizar la generación de tono. El estado de llamada de hdCall puede ser cualquier estado excepto inactivo.

dwEndToEndID

Identificador único e ininterpretado de la solicitud para toda su duración, es decir, hasta que se envía el mensaje de LINE_GENERATE coincidente. El proveedor de servicios incluye este identificador como uno de los parámetros del mensaje.

dwToneMode

Define el tono que se va a generar. Los tonos pueden ser estándar o personalizados. Un tono personalizado se compone de un conjunto de frecuencias arbitrarias. Se predefini un pequeño número de tonos estándar. DwDuration especifica la duración del tono para tonos estándar y personalizados. Si dwToneMode se establece en cero, se cancela cualquier generación de dígitos o tono en curso. Este parámetro usa una y solo una de las constantes LINETONEMODE_.

dwDuration

Duración en milisegundos durante el cual se mantiene el tono. Un valor de 0 para dwDuration usa una duración predeterminada para el tono especificado. Estos son los valores predeterminados:

PERSONALIZADO: infinito

RINGBACK: infinito

OCUPADO: infinito

BEEP: infinito

FACTURACIÓN: fijo (ciclo único)

TAPI no valida este parámetro cuando se llama a esta función.

dwNumTones

Número de entradas de la matriz lpTones . Este parámetro se omite si dwToneMode no es igual a LINETONEMODE_CUSTOM.

lpTones

Puntero a una matriz LINEGENERATETONE que especifica los componentes del tono. Este parámetro se omite para los tonos no personalizados. Si lpTones es un tono multifrecuencia, los distintos tonos se reproducen simultáneamente.

Valor devuelto

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

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

Comentarios

TSPI_lineGenerateTone devuelve cero (éxito) cuando la generación de tonos se inicia correctamente; no cuando finaliza la generación del tono. La función permite la generación de bandas de varios tonos predefinidos, como ringback, tonos ocupados y pitido. También permite la fabricación de tonos personalizados especificando sus frecuencias de componente, cadencia y volumen, si es compatible con el proveedor de servicios. Dado que estos tonos se generan como tonos de banda, la llamada normalmente tendría que estar en estado conectado para que la generación de tonos sea eficaz. Cuando se completa la generación de tonos o cuando se cancela la generación de tonos, se envía un mensaje de LINE_GENERATE a TAPI.

Nota Solo se permite que una solicitud de generación de banda (generación de tono o generación de dígitos) esté en curso por llamada. Esto implica que si la generación de tonos está actualmente en curso en una llamada, invocando TSPI_lineGenerateDigits o TSPI_lineGenerateTone cancela la generación de tonos. El proveedor de servicios debe finalizar cualquier generación de tonos en curso cuando se invoca una función de TSPI_lineGenerateDigits o TSPI_lineGenerateTone posterior.

La función correspondiente en el nivel tapi no incluye el parámetro formal dwEndToEndID. En ese nivel, no hay ningún marcado de un extremo a otro. TAPI usa el marcado de un extremo a otro en el nivel de TSPI para distinguir una solicitud de TSPI_lineGenerateTone de otra.