fonction lineGenerateDigits (tapi.h)

Article
03/02/2024

La fonction lineGenerateDigits lance la génération des chiffres spécifiés sur l’appel spécifié en tant que tonalités inband à l’aide du mode de signalisation spécifié. L’appel de cette fonction avec une valeur NULL pour lpszDigits annule toute génération de chiffres en cours. L’appel de lineGenerateDigits ou lineGenerateTone lorsque la génération de chiffres est en cours annule la génération de chiffres ou de tonalité actuelle et lance la génération des derniers chiffres ou tonalités spécifiés.

Syntaxe

LONG lineGenerateDigits(
  HCALL  hCall,
  DWORD  dwDigitMode,
  LPCSTR lpszDigits,
  DWORD  dwDuration
);

Paramètres

hCall

Gérer l’appel. L’application doit être propriétaire de l’appel. L’état d’appel de hCall peut être n’importe quel état. TAPI n’impose aucune exigence d’état d’appel, mais certains fournisseurs de services Tapi peuvent exiger que le hCall soit dans l’état LINECALLSTATE_CONNECTED.

dwDigitMode

Format à utiliser pour signaler ces chiffres. N’oubliez pas que dwDigitMode ne peut avoir qu’un seul jeu d’indicateurs. Ce paramètre utilise l’une des constantes LINEDIGITMODE_.

lpszDigits

Pointeur vers une mémoire tampon de caractères avec fin null qui contient les chiffres à générer. Les caractères valides sont ceux spécifiés pour les constantes LINEDIGITMODE_ fournies dans dwDigitModes.

En outre, la virgule (,) est également un caractère valide. Une virgule injecte un délai supplémentaire entre la signalisation des chiffres précédents et suivants qu’elle sépare. La durée de cette pause est définie par la configuration, et les fonctionnalités de l’appareil de ligne indiquent cette durée. Plusieurs virgules peuvent être utilisées pour injecter des pauses plus longues. Les chiffres non valides sont ignorés pendant la génération, plutôt que d’être signalés comme des erreurs.

L’exclamation ( !) est un caractère valide. Ce caractère provoque une opération « hookflash », comme décrit pour les adresses accessibles en numérotation.

dwDuration

Durée en millisecondes de chiffres DTMF et d’espacement d’impulsions et d’inter-chiffres DTMF. La valeur 0 utilise une valeur par défaut. Le paramètre dwDuration doit se trouver dans la plage spécifiée par MinDialParams et MaxDialParams dans LINEDEVCAPS. Si elle n’est pas comprise, la valeur réelle est définie sur la valeur la plus proche de la plage.

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_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarques

La fonction lineGenerateDigits est considérée comme ayant réussi lorsque la génération de chiffres a été lancée avec succès, et non lorsque tous les chiffres ont été générés. Contrairement à lineDial, qui compose les chiffres de façon dépendante du réseau, lineGenerateDigits garantit de produire les chiffres sous forme de tonalités de bande sur le canal vocal à l’aide d’impulsions DTMF ou de commutateur de crochet lors de l’utilisation d’impulsions. La fonction lineGenerateDigits ne convient généralement pas pour passer des appels ou composer. Il est destiné à la signalisation de bout en bout sur un appel établi.

Une fois que tous les chiffres dans lpszDigits ont été générés ou après que la génération de chiffres a été abandonnée ou 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. La génération de chiffres sur un appel est annulée en lançant une autre demande de génération de chiffres ou une demande de génération de tonalité. Pour annuler la génération de chiffres actuelle, l’application peut appeler lineGenerateDigits et spécifier NULL pour le paramètre lpszDigits .

Selon le fournisseur de services et le matériel, l’application peut surveiller les chiffres qu’elle génère elle-même. Si ce n’est pas souhaité, l’application peut désactiver la surveillance des chiffres lors de la génération de chiffres.