Función lineGenerateTone (tapi.h)

Artículo
03/02/2024

La función lineGenerateTone genera el tono de banda especificado a través de la llamada especificada. Invocar esta función con un cero para dwToneMode anula la generación de tonos actualmente en curso en la llamada especificada. Invocar lineGenerateTone o lineGenerateDigits mientras la generación de tonos está en curso anula la generación de tono actual o la generación de dígitos e inicia la generación del tono o dígitos recién especificados.

Sintaxis

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parámetros

hCall

Controla la llamada en la que se va a generar un tono. La aplicación debe ser propietario de la llamada. El estado de llamada de hCall puede ser cualquier estado.

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. La duración del tono se especifica con dwDuration para tonos estándar y personalizados. El parámetro dwToneMode solo puede tener un conjunto de bits. Si no se establece ningún bits (se pasa el valor 0), se cancela la generación de tonos. Este parámetro usa una de las constantes de LINETONEMODE_.

dwDuration

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

PERSONALIZADO: el tono se mantiene hasta que se apaga, normalmente por la interacción del usuario o un tiempo de espera del equipo.

RINGBACK: el tono se mantiene hasta que se apaga, normalmente por la interacción del usuario o un tiempo de espera del equipo.

OCUPADO: El tono se mantiene hasta que se apaga, normalmente por la interacción del usuario o un tiempo de espera del equipo.

BEEP: El tono se mantiene hasta que se apaga, normalmente por la interacción del usuario o un tiempo de espera del equipo.

FACTURACIÓN: fijo (ciclo único).

dwNumTones

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

lpTones

Puntero a una matriz LINEGENERATETONE que especifica los componentes del tono. Este parámetro se omite para los tonos constantes de LINETONEMODE_ estándar, como LINETONEMODE_BUSY. Si lpTones es un tono multifrecuencia, los distintos tonos se reproducen simultáneamente.

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_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Comentarios

La función lineGenerateTone se considera que se ha completado correctamente cuando la generación de tonos se ha iniciado 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. 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 del tono o cuando se cancela la generación de tonos, se envía un mensaje LINE_GENERATE a la aplicación.

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 en todas las aplicaciones que sean propietarios de la llamada. Esto implica que si la generación de tonos está actualmente en curso en una llamada, la invocación de lineGenerateDigits cancela la generación de tonos.

Si se devuelve el valor de error LINEERR_INVALPOINTER, el parámetro lpTones especificado no es válido o el valor especificado por el parámetro dwNumTones es demasiado grande.