fonction lineGatherDigits (tapi.h)

Article
08/26/2023

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

Syntaxe

LONG lineGatherDigits(
  HCALL  hCall,
  DWORD  dwDigitModes,
  LPSTR  lpsDigits,
  DWORD  dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD  dwFirstDigitTimeout,
  DWORD  dwInterDigitTimeout
);

Paramètres

hCall

Gérer l’appel sur lequel les chiffres doivent être collectés. L’application doit être propriétaire de l’appel. L’état d’appel de hCall peut être n’importe quel état.

dwDigitModes

Modes numériques à surveiller. Ce paramètre utilise une ou plusieurs constantes LINEDIGITMODE_.

lpsDigits

Pointeur vers la mémoire tampon où les chiffres détectés doivent être stockés sous forme de caractères de texte. Les chiffres peuvent ne pas apparaître dans la mémoire tampon un par un, car ils sont collectés. Ce n’est qu’après réception d’un message LINE_GATHERDIGITS que le contenu de la mémoire tampon est considéré comme valide. Si lpsDigits a la valeur NULL, la collecte de chiffres en cours sur l’appel est terminée et dwNumDigits est ignorée. 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 à l’application. Le paramètre dwNumDigits est ignoré lorsque lpsDigits a la valeur NULL. Cette fonction échoue si dwNumDigits est égal à zéro.

lpszTerminationDigits

Chaîne terminée par null de chiffres d’arrêt sous forme de caractères de texte. Si l’un des chiffres de la chaîne est détecté, ce chiffre de terminaison est ajouté à la mémoire tampon, la collection de chiffres est terminée et le message LINE_GATHERDIGITS est envoyé à l’application.

La liste des caractères valides dépend de la constante fournie dans dwDigitModes. Pour obtenir la liste des caractères valides pour chaque mode possible, consultez constantes LINEDIGITMODE_.

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 dans laquelle le premier chiffre est attendu. Si le premier chiffre n’est pas reçu dans cette période, la collecte de chiffres est abandonnée et un message LINE_GATHERDIGITS est envoyé à l’application. La mémoire tampon contient uniquement le caractère NULL , indiquant qu’aucun chiffre n’a été reçu et que le premier délai d’expiration a terminé la collecte des chiffres. 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.

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 abandonnée et un message LINE_GATHERDIGITS est envoyé à l’application. La mémoire tampon contient uniquement les chiffres collectés jusqu’à ce point, suivis d’un caractère NULL , indiquant qu’un délai d’expiration interdigit a arrêté la collecte de chiffres. 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.

Valeur retournée

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

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarques

La collecte de chiffres est terminée lorsque le nombre de chiffres demandé a été collecté. Elle est également terminée quand 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.

Une autre façon d’annuler la collecte de chiffres se produit lorsque 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.

Une quatrième méthode pour mettre fin à la collection de chiffres consiste à appeler à nouveau cette fonction pendant que la collection est en cours. L’ancienne session de collecte est terminée, tous les chiffres collectés jusqu’à ce point sont copiés dans la mémoire tampon fournie à partir de l’appel précédent à cette fonction, et la mémoire tampon est remise lorsque le message LINE_GATHERDIGITS est envoyé à l’application. Le mécanisme permettant de terminer la collecte de chiffres sans lancer une autre collecte des chiffres consiste à appeler cette fonction avec lpsDigits égal à NULL.

Cette fonction est considérée comme réussie si la collecte de chiffres a été correctement lancée, et non si la collecte 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 NULL .

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

Le message LINE_GATHERDIGITS est envoyé uniquement à l’application qui a lancé la demande. 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 une autre demande lineGatherDigits sur l’appel. Une seule demande de chiffres de collecte peut être active sur un appel à un moment donné dans toutes les applications propriétaires de l’appel. Étant donné le comportement asynchrone de l’opération, une application qui émet plusieurs demandes lineGatherDigits en succession rapide peut être en mesure de le faire et de recevoir plusieurs messages LINE_GATHERDIGITS ultérieurement. Bien qu’il s’agit d’un comportement d’application inhabituel, l’application est en mesure de compter le nombre de ces messages pour permettre la mise en correspondance des messages d’annulation avec les demandes précédentes. Dans tous les cas, seule la demande la plus récente doit être considérée comme valide.

Note Lorsqu’une application appelle une opération asynchrone qui réécrit des données dans la mémoire de l’application, l’application doit conserver cette mémoire disponible pour l’écriture jusqu’à ce qu’un message LINE_REPLY ou LINE_GATHERDIGITS soit reçu.

Une application peut utiliser lineMonitorDigits pour activer ou désactiver la détection de chiffres non débogués. Chaque fois qu’un chiffre est détecté de cette façon, un message LINE_MONITORDIGITS est envoyé à l’application. La détection de chiffres mis en mémoire tampon et sans tampon peut être activée simultanément pour le même appel.

La collecte de chiffres lors d’une téléconférence s’applique uniquement à hConfCall, et non aux appels individuels participants.

Si la fonction lineGatherDigits est utilisée pour annuler une demande précédente de collecte de chiffres, la fonction copie tous les chiffres collectés jusqu’à ce point dans la mémoire tampon spécifiée dans l’appel de fonction d’origine. La fonction envoie ensuite un message LINE_GATHERDIGITS à l’application, que le paramètre lpszDigits dans le deuxième appel spécifie une adresse NULL ou une adresse différente.