fonction TSPI_lineMonitorTones (tspi.h)

Article
03/03/2024

La fonction TSPI_lineMonitorTones active et désactive la détection des tonalités inband sur l’appel. Chaque fois qu’un ton spécifié est détecté, un message est envoyé à l’application cliente via TAPI.

Syntaxe

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

Paramètres

hdCall

Handle de l’appel pour lequel la détection de tonalité doit être effectuée. L’état de l’appel de hdCall peut être n’importe quel état, sauf inactif.

dwToneListID

Identificateur unique de cette liste de tons. Plusieurs listes de tonalités peuvent être exceptionnelles à la fois. Le fournisseur de services doit remplacer toute ancienne liste ayant le même dwToneListID par la nouvelle liste de tonalités. Si lpToneList a la valeur NULL, la liste de tonalités avec dwToneListID est simplement supprimée. Dans tous les cas, les autres listes de tonalités avec des dwToneListIDdifférents sont conservées inchangées.

lpToneList

Liste de tonalités à surveiller, de type LINEMONITORTONE. Chaque tonalité de cette liste a un champ de balise défini par l’application qui est utilisé pour identifier les tons individuels dans la liste afin de signaler une détection de tonalité. L’analyse de tonalité en cours est annulée ou modifiée en appelant cette opération avec null pour lpToneList ou avec une autre liste de tonalités. Le fournisseur de services doit copier la liste de tonalités dans sa propre mémoire pour une référence ultérieure, au lieu de simplement conserver le pointeur dans la mémoire de l’application.

dwNumEntries

Nombre d’entrées dans lpToneList. Le paramètre dwNumEntries est ignoré si lpToneList a la valeurNULL. TAPI ne valide pas ce paramètre 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_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Remarques

Cette fonction retourne zéro (réussite) lorsque l’analyse de tonalité est correctement lancée, et non lorsque l’analyse de tonalité est terminée. Comme pour la surveillance des médias, la surveillance de la tonalité reste en vigueur pour une liste de tonalités donnée jusqu’à ce que cette liste de tonalités soit explicitement désactivée en appelant TSPI_lineMonitorTones avec le même dwToneListID et une autre liste de tonalités (ou une liste de tonalités NULL ), ou jusqu’à ce que l’appel passe à inactif.

Bien que cette fonction puisse être appelée dans n’importe quel état d’appel, sauf inactif, les tonalités ne peuvent généralement être détectées que lorsque l’appel est dans l’état connecté . La détection de tonalité nécessite généralement des ressources de calcul. Selon le fournisseur de services et d’autres activités qui sont en concurrence pour de telles ressources, le nombre de tonalités qui peuvent être détectées peut varier au fil du temps. En outre, une quantité équivalente de ressources peut être consommée pour la surveillance d’un seul tonalité de fréquence triple par rapport à trois tonalités de fréquence unique. Si les ressources sont surcommises, le fournisseur de services retourne LINEERR_RESOURCEUNAVAIL.

Le fournisseur de services surveille simultanément toutes les tonalités de toutes les listes de tonalités. Lorsqu’un ton est détecté, chaque tonalité correspondante de chaque liste de tons est signalée séparément à l’aide d’un message LINE_MONITORTONE . Chaque rapport de tonalité inclut à la fois l’identificateur de liste de tonalités et la balise spécifique à l’application. Certains fournisseurs de services peuvent ne pas être en mesure de discriminer des tons très proches, de sorte que plusieurs correspondances peuvent être signalées même pour les tons dont les descriptions ne sont pas strictement identiques.

NotezTSPI_lineMonitorTones est également utilisé pour détecter le silence. Le silence est spécifié sous forme de tonalité avec toutes les fréquences nulles.

La fonction correspondante au niveau TAPI n’inclut pas de paramètre dwToneListID . L’inclusion de ce paramètre à l’interface TSPI permet à TAPI de transférer l’union de toutes les listes d’analyse de tonalité de toutes les applications au fournisseur de services, tout en conservant la possibilité de filtrer et de transférer les événements de détection de tonalité en fonction de l’application. Cela donne aux concepteurs de fournisseurs de services la flexibilité maximale pour déterminer la mesure dans laquelle ils peuvent discriminer des tons très proches, car TAPI ne fait aucune hypothèse sur les descriptions de tonalités considérées comme identiques.