fonction TSPI_lineMonitorMedia (tspi.h)

Article
08/26/2023

La fonction TSPI_lineMonitorMedia active et désactive la détection des types de médias sur l’appel spécifié. Lorsqu’un type de média est détecté, un message LINE_MONITORMEDIA est envoyé à TAPI.

Syntaxe

LONG TSPIAPI TSPI_lineMonitorMedia(
  HDRVCALL hdCall,
  DWORD    dwMediaModes
);

Paramètres

hdCall

Handle de l’appel pour lequel l’analyse multimédia doit être définie. L’état de l’appel de hdCall peut être n’importe quel état, sauf inactif.

dwMediaModes

Types de médias à surveiller. Le paramètre dwMediaModes peut avoir l’une des constantes LINEMEDIAMODE_.

La valeur 0 annule l’analyse de tous les types de médias.

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_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarques

Le fournisseur de services retourne LINEERR_INVALMEDIAMODE si la liste des types de médias à surveiller contient des informations non valides.

Cette fonction retourne zéro (réussite) lorsque l’analyse du type de média a été correctement lancée, et non lorsque l’analyse du type de média a pris fin. La surveillance des médias pour un type de média donné reste en vigueur jusqu’à ce qu’elle soit explicitement désactivée en appelant TSPI_lineMonitorMedia avec un paramètre dwMediaModes avec le type de média défini sur zéro, ou jusqu’à ce que l’appel passe au mode inactif.

TSPI_lineMonitorMedia est principalement un mécanisme de rapport d’événements. Le type de média d’un appel, comme indiqué dans LINECALLINFO, n’est pas affecté par la détection du type de média par le fournisseur de services. Seul TAPI ou une application cliente peut modifier le type de média indiqué d’un appel à l’aide de TSPI_lineSetMediaMode. L’utilisation réelle d’un type de média particulier se produit via des API de flux multimédia distinctes (telles que Comm ou WAVE).

L’analyse multimédia par défaut effectuée par le fournisseur de services pour une nouvelle apparence d’appel correspond à l’union de tous les types de médias spécifiés par TSPI_lineSetDefaultMediaDetection. Peu de temps après l’établissement d’un nouvel appel, TAPI appelle généralement TSPI_lineMonitorMedia pour réduire l’ensemble des types de médias détectés et signalés pour cet appel à l’union de tous les types de médias souhaités par les applications clientes de l’appel.

Le fournisseur de services doit annuler la surveillance des médias lorsqu’un appel est inactif. TAPI doit calculer l’union des types de médias souhaités par tous les clients et passer le résultat à cette fonction. Le fournisseur de services utilise l’ensemble passé à cette fonction par TAPI.

Bien que cette fonction puisse être appelée dans n’importe quel état d’appel, le type de média d’un appel ne peut généralement être détecté que lorsque l’appel est dans certains états d’appel. Ces états peuvent être spécifiques à l’appareil. Par exemple, dans ISDN, un message peut indiquer le type de média du flux multimédia avant que le flux multimédia n’existe. De même, la sonnerie distinctive ou les informations d’ID appelées sur l’appel peuvent être utilisées pour identifier le type de média d’un appel. Sinon, l’appel peut devoir recevoir une réponse (appel à l’état connecté ) pour permettre à un fournisseur de services de déterminer le type de média de l’appel en filtrant le flux multimédia. Étant donné que le filtrage du flux multimédia d’un appel implique une surcharge de calcul, TAPI utilise généralement cette procédure pour désactiver l’analyse multimédia lorsqu’elle n’est pas nécessaire.

Étant donné que la détection en mode multimédia activée par TSPI_lineMonitorMedia est implémentée en tant qu’opération en lecture seule du flux multimédia de l’appel, elle n’est pas perturbatrice. Aucun signal n’est envoyé sur la ligne à la suite de la définition de TSPI_lineMonitorMedia.

En ce qui concerne le type de média transmis, TAPI garantit qu’aucun bits réservé n’est défini. Le fournisseur de services doit effectuer d’autres vérifications de validité sur les types de médias, par exemple vérifier si les types de médias sont effectivement pris en charge par le fournisseur de services.