TSPI_lineGenerateTone, fonction (tspi.h)

Article
08/26/2023

La fonction TSPI_lineGenerateTone génère l’inband de tonalité spécifié sur l’appel spécifié. L’appel de cette fonction avec un zéro pour dwToneMode abandonne toute génération de tonalité en cours sur l’appel spécifié. L’appel de TSPI_lineGenerateTone ou de TSPI_lineGenerateDigits alors que la génération de tonalités est en cours abandonne la génération de tonalités en cours ou la génération de chiffres en cours et lance la génération du ou des chiffres nouvellement spécifiés.

Syntaxe

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

Paramètres

hdCall

Handle du fournisseur de services à l’appel sur lequel la génération de tonalité doit être effectuée. L’état d’appel de hdCall peut être n’importe quel état sauf inactif.

dwEndToEndID

Identificateur unique et non interprété de la demande pendant toute sa durée de vie, c’est-à-dire jusqu’à ce que le message LINE_GENERATE correspondant soit envoyé. Le fournisseur de services inclut cet identificateur comme l’un des paramètres du message.

dwToneMode

Définit la tonalité à générer. Les tonalités peuvent être standard ou personnalisées. Une tonalité personnalisée est composée d’un ensemble de fréquences arbitraires. Un petit nombre de tonalités standard sont prédéfinies. La durée de la tonalité est spécifiée par dwDuration pour les tonalités standard et personnalisées. Si dwToneMode est défini sur zéro, toute génération de chiffres ou de tonalités en cours est annulée. Ce paramètre utilise une seule des constantes LINETONEMODE_.

dwDuration

Durée, en millisecondes, pendant laquelle la tonalité est maintenue. La valeur 0 pour dwDuration utilise une durée par défaut pour la tonalité spécifiée. Les valeurs par défaut sont :

CUSTOM : infini

RINGBACK : infini

BUSY : infini

BEEP : infini

FACTURATION : fixe (cycle unique)

Ce paramètre n’est pas validé par TAPI lorsque cette fonction est appelée.

dwNumTones

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

lpTones

Pointeur vers un tableau LINEGENERATETONE qui spécifie les composants de la tonalité. Ce paramètre est ignoré pour les tonalités non personnalisées. Si lpTones est une tonalité à fréquences multiples, les différentes tonalités sont lues simultanément.

Valeur retournée

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

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

Remarques

TSPI_lineGenerateTone retourne zéro (réussite) lorsque la génération de tonalités est lancée avec succès ; pas lorsque la génération du ton est terminée. La fonction permet la génération en bande de plusieurs tonalités prédéfinies, telles que le sonnerie, les tonalités occupées et le signal sonore. Il permet également la fabrication de tonalités personnalisées en spécifiant leurs fréquences de composant, leur cadence et leur volume, si cela est pris en charge par le fournisseur de services. Étant donné que ces tonalités sont générées en tant que tonalités inband, l’appel doit généralement être dans l’état connecté pour que la génération de tonalités soit efficace. Lorsque la génération de tonalités est terminée ou quand la génération de tonalités est annulée, un message LINE_GENERATE est envoyé à TAPI.

Note 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. Cela implique que si la génération de tonalités est en cours lors d’un appel, l’appel de TSPI_lineGenerateDigits ou TSPI_lineGenerateTone annule la génération de tonalités. Le fournisseur de services doit arrêter toute génération de tonalité en cours lorsqu’une fonction de TSPI_lineGenerateDigits ou de TSPI_lineGenerateTone suivante est appelée.

La fonction correspondante au niveau TAPI n’inclut pas le paramètre formel dwEndToEndID. À ce niveau, il n’y a pas de marquage de bout en bout. TAPI utilise le marquage de bout en bout au niveau TSPI pour distinguer une requête TSPI_lineGenerateTone d’une autre.