fonction lineGenerateTone (tapi.h)

Article
08/26/2023

La fonction lineGenerateTone génère la tonalité de la bande spécifiée sur l’appel spécifié. L’appel de cette fonction avec un zéro pour dwToneMode annule la génération de tonalité actuellement en cours sur l’appel spécifié. L’appel de lineGenerateTone ou lineGenerateDigits alors que la génération de tonalité est en cours annule la génération de tonalité ou de chiffres actuelle et lance la génération du ou des chiffres nouvellement spécifiés.

Syntaxe

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

Paramètres

hCall

Gérez l’appel sur lequel un ton doit être généré. L’application doit être propriétaire de l’appel. L’état d’appel de hCall peut être n’importe quel état.

dwToneMode

Définit le ton à générer. Les tonalités peuvent être standard ou personnalisées. Un ton personnalisé est composé d’un ensemble de fréquences arbitraires. Un petit nombre de tons standard sont prédéfinis. La durée de la tonalité est spécifiée avec dwDuration pour les tonalités standard et personnalisées. Le paramètre dwToneMode ne peut avoir qu’un seul jeu de bits. Si aucun bits n’est défini (la valeur 0 est passée), la génération de tonalité est annulée. Ce paramètre utilise l’une des constantes LINETONEMODE_.

dwDuration

Durée en millisecondes pendant laquelle le ton doit être soutenu. La valeur 0 pour dwDuration utilise une durée par défaut pour le ton spécifié. Les valeurs par défaut sont :

CUSTOM : le ton est maintenu jusqu’à ce qu’il soit éteint, généralement par l’interaction de l’utilisateur ou un délai d’arrêt de l’équipement.

RINGBACK : Le ton est maintenu jusqu’à ce qu’il soit éteint, généralement par l’interaction de l’utilisateur ou un délai d’arrêt de l’équipement.

OCCUPÉ : Le ton est maintenu jusqu’à ce qu’il soit éteint, généralement par l’interaction de l’utilisateur ou un délai d’arrêt de l’équipement.

BEEP : Le ton est maintenu jusqu’à ce qu’il soit éteint, généralement par l’interaction de l’utilisateur ou un délai d’arrêt de l’équipement.

FACTURATION : fixe (cycle unique).

dwNumTones

Nombre d’entrées dans le tableau lpTones . Ce paramètre est ignoré si dwToneMode n’est pas égal à CUSTOM.

lpTones

Pointeur vers un tableau LINEGENERATETONE qui spécifie les composants du ton. Ce paramètre est ignoré pour les tons de constantes standard LINETONEMODE_ , comme LINETONEMODE_BUSY. Si lpTones est un ton multiréfréquence, les différentes tonalités sont jouées simultanément.

Valeur retournée

Retourne zéro si la requête réussit ou un numéro d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarques

La fonction lineGenerateTone est considérée comme ayant réussi lorsque la génération de tonalité a été lancée avec succès, et non lorsque la génération de la tonalité est terminée. La fonction permet la génération de plusieurs tonalités prédéfinies, telles que les sonneries, les tonalités occupées et le bip. Il permet également la fabrication de tonalités personnalisées en spécifiant leurs fréquences, cadences et volume. Étant donné que ces tonalités sont générées en tant que tonalités inband, l’appel doit généralement être à l’état connecté pour que la génération de tonalités soit efficace. Lorsque la génération de la tonalité est terminée ou lorsque la génération de tonalité est annulée, un message LINE_GENERATE est envoyé à l’application.

Une seule demande de génération inband (génération de tonalité ou génération de chiffres) est autorisée à être en cours par appel pour toutes les applications propriétaires de l’appel. Cela implique que si la génération de tonalités est actuellement en cours sur un appel, l’appel de lineGenerateDigits annule la génération de tonalités.

Si la valeur d’erreur LINEERR_INVALPOINTER est retournée, le paramètre lpTones spécifié n’est pas valide ou la valeur spécifiée par le paramètre dwNumTones est trop grande.