TSPI_lineGatherDigits, fonction (tspi.h)

Article
03/03/2024

La fonction TSPI_lineGatherDigits lance la collecte en mémoire tampon des chiffres sur l’appel spécifié. TAPI spécifie une mémoire tampon dans laquelle placer les chiffres et le nombre maximal de chiffres à collecter.

Syntaxe

LONG TSPIAPI TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD    dwEndToEndID,
  DWORD    dwDigitModes,
  LPWSTR   lpsDigits,
  DWORD    dwNumDigits,
  LPCWSTR  lpszTerminationDigits,
  DWORD    dwFirstDigitTimeout,
  DWORD    dwInterDigitTimeout
);

Paramètres

hdCall

Handle du fournisseur de services pour l’appel sur lequel la collecte de chiffres 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 de LINE_GATHERDIGITS correspondant soit envoyé. Le fournisseur de services inclut cet identificateur comme l’un des paramètres du message.

dwDigitModes

Mode(s) numérique(s) à surveiller. Ce paramètre utilise une ou plusieurs des constantes LINEDIGITMODE_ suivantes.

Valeur	Signification
LINEDIGITMODE_PULSE	Détectez les chiffres en tant que clics audibles résultant de l’utilisation de séquences d’impulsions rotatives. Les chiffres valides pour le mode d’impulsion sont de « 0 » à « 9 ».
LINEDIGITMODE_DTMF	Détecter les chiffres en tant que tonalités DTMF. Les chiffres valides pour le mode DTMF sont « 0 » à « 9 », « A », « B », « C », « D », « * », « # ».

lpsDigits

Pointeur vers la mémoire tampon où les chiffres détectés doivent être stockés en tant que caractères de texte. Le fournisseur de services peut, mais n’est pas tenu de le faire, placer des chiffres dans la mémoire tampon un par un au fur et à mesure qu’ils sont collectés. Lorsque le message LINE_GATHERDIGITS est envoyé, le contenu de la mémoire tampon doit être complet. Si lpsDigits est spécifié comme NULL , la collecte de chiffres en cours sur l’appel est annulée et le paramètre dwNumDigits est ignoré. Sinon, lpsDigits est supposé avoir de la place pour les chiffres dwNumDigits .

dwNumDigits

Nombre de chiffres à collecter avant l’envoi d’un message LINE_GATHERDIGITS à TAPI. Le paramètre dwNumDigits est ignoré lorsque lpsDigits a la valeur NULL. Cette fonction doit retourner une LINEERR_INVALPARAM si dwNumDigits est égal à zéro.

lpszTerminationDigits

Pointeur vers une chaîne Unicode terminée par un caractère null contenant des chiffres de terminaison en tant que caractères de texte. Si l’un des chiffres de la chaîne est détecté, ce chiffre d’arrêt est ajouté à la mémoire tampon, la collection de chiffres est terminée et le message LINE_GATHERDIGITS est envoyé à TAPI.

Les caractères valides pour le mode d’impulsion sont « 0 » à « 9 ». Les caractères valides pour le mode DTMF sont « 0 » à « 9 », « A », « B », « C », « D », « * », « # ». Si ce pointeur a la valeur NULL ou s’il pointe vers une chaîne vide, la fonction se comporte comme si aucun chiffre de terminaison n’avait été fourni.

dwFirstDigitTimeout

Durée, en millisecondes, pendant laquelle le premier chiffre est attendu. Si le premier chiffre n’est pas reçu pendant cette période, la collecte de chiffres est terminée et un message LINE_GATHERDIGITS est envoyé à TAPI. Un seul caractère NULL est écrit dans la mémoire tampon, indiquant qu’aucun chiffre n’a été reçu et que la collecte du premier chiffre a pris fin au délai d’expiration. Les fonctionnalités de l’appareil de ligne de l’appel spécifient la plage valide pour ce paramètre ou indiquent que les délais d’expiration ne sont pas pris en charge. Ce paramètre n’est pas validé par TAPI lorsque cette fonction est appelée.

dwInterDigitTimeout

Durée maximale, en millisecondes, entre les chiffres consécutifs. Si aucun chiffre n’est reçu pendant cette période, la collecte de chiffres est terminée et un message LINE_GATHERDIGITS est envoyé à TAPI. Un seul caractère NULL est écrit dans la mémoire tampon, indiquant qu’un délai d’expiration interdigit a arrêté la collecte de chiffres. La structure LINEDEVCAPS doit spécifier la plage valide pour ce paramètre ou indiquer que les délais d’expiration ne sont pas pris en charge. Ce paramètre n’est pas validé par TAPI lorsque cette fonction est appelée.

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_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.

Remarques

Le fournisseur de services retourne LINEERR_INVALPARAM si le paramètre dwNumDigits n’est pas valide.

Cette fonction retourne zéro (réussite) si la collecte de chiffres est correctement lancée ; non si la collection de chiffres s’est terminée. Dans tous les cas où une mémoire tampon partielle est retournée, les chiffres valides (le cas échéant) sont suivis d’un caractère Unicode NULL.

La collecte de chiffres peut être terminée des manières suivantes :

Le nombre de chiffres demandé peut avoir été collecté.
L’un des chiffres détectés correspond à un chiffre dans szTerminationDigits avant que le nombre spécifié de chiffres ait été collecté. Le chiffre d’arrêt détecté est également placé dans la mémoire tampon et la mémoire tampon partielle est retournée.
L’un des délais d’expiration expire. La valeur dwFirstDigitTimeout expire si le premier chiffre n’est pas reçu au cours de cette période. L’objet dwInterDigitTimout expire si le deuxième, troisième chiffre (et ainsi de suite) n’est pas reçu pendant cette période à partir du chiffre détecté précédemment, et qu’une mémoire tampon partielle est retournée.
Appel de cette opération alors que la collecte est en cours. L’ancienne session de collection est terminée et le contenu de l’ancienne mémoire tampon n’est pas défini. Pour annuler la collecte de chiffres sans lancer une autre opération, cette opération est appelée avec lpsDigits égal à NULL.

Bien que cette fonction puisse être appelée dans n’importe quel état d’appel sauf inactif, les chiffres ne peuvent généralement être collectés que lorsque l’appel est dans l’état connecté .

Le message LINE_GATHERDIGITS est normalement envoyé lorsque la mémoire tampon de chiffres est remplie. Il est également envoyé lorsque des mémoires tampons partielles sont retournées en raison de délais d’expiration ou de chiffres d’arrêt correspondants, ou lorsque la demande est annulée par le biais d’une autre demande de TSPI_lineGatherDigits sur l’appel. Une seule demande de chiffres de collecte peut être active à la fois. Le fournisseur de services doit mettre fin à toute opération de collecte en attente avec un message LINE_GATHERDIGITS lorsque TSPI_lineGatherDigits est appelé.

Lorsque l’opération associée à un appel à la fonction TSPI_lineGatherDigits est annulée (par un appel ultérieur à la fonction), le fournisseur de services copie tous les chiffres collectés jusqu’à ce point dans la mémoire tampon spécifiée dans l’appel d’origine.

TAPI peut utiliser TSPI_lineMonitorDigits pour activer ou désactiver la détection de chiffres sans tampon. Chaque fois qu’un chiffre est détecté de cette façon, un message LINE_MONITORDIGITS est envoyé à TAPI. La détection de chiffres mis en mémoire tampon (collecter des chiffres) et non tamponnée peut être activée simultanément pour le même appel.

Le fournisseur de services est autorisé à varier quelque peu la qualité du minutage qu’il utilise pour cette fonction, y compris ne pas effectuer de minutages du tout. La qualité du minutage est signalée dans LINEDEVCAPS, dans les membres dwGatherDigitsMinTimeout et dwGatherDigitsMaxTimeout.

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 demande TSPI_lineGatherDigits d’une autre.