TSPI_lineSetMediaControl, fonction (tspi.h)

Article
03/03/2024

La fonction TSPI_lineSetMediaControl active et désactive les actions de contrôle sur le flux multimédia associé à la ligne, à l’adresse ou à l’appel spécifiés. Les actions de contrôle des médias peuvent être déclenchées par la détection de chiffres, de types de médias, de tonalités personnalisées et d’états d’appel spécifiés. Les nouveaux contrôles multimédias spécifiés remplacent tous ceux qui étaient en vigueur pour cette ligne, cette adresse ou cet appel avant cette demande.

Syntaxe

LONG TSPIAPI TSPI_lineSetMediaControl(
  HDRVLINE                          hdLine,
  DWORD                             dwAddressID,
  HDRVCALL                          hdCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Paramètres

hdLine

Handle d’une ligne.

dwAddressID

Adresse sur l’appareil de ligne ouverte donné. Un identificateur d’adresse est associé de manière permanente à une adresse ; l’identificateur reste constant entre les mises à niveau du système d’exploitation. TAPI ne valide pas ce paramètre lorsque cette fonction est appelée.

hdCall

Handle à un appel. L’état d’appel de hdCall peut être n’importe quel état.

dwSelect

Spécifie si le contrôle multimédia demandé est associé à un seul appel, est la valeur par défaut pour tous les appels sur une adresse ou est la valeur par défaut pour tous les appels sur une ligne. Ce paramètre utilise les constantes LINECALLSELECT_ suivantes.

lpDigitList

Pointeur vers le tableau qui contient les chiffres qui doivent déclencher des actions de contrôle de média, de type LINEMEDIACONTROLDIGIT. Chaque fois qu’un chiffre répertorié dans la liste de chiffres est détecté, l’action de contrôle de média spécifiée est effectuée sur le flux multimédia de l’appel.

Les chiffres valides pour le mode d’impulsion sont de « 0 » à « 9 ». Les chiffres valides pour le mode DTMF sont « 0 » à « 9 », « A », « B », « C », « D », « * », « # ».

dwDigitNumEntries

Nombre d’entrées dans l’objet lpDigitList. TAPI ne valide pas ce paramètre lorsque cette fonction est appelée.

lpMediaList

Pointeur vers un tableau avec des entrées de type LINEMEDIACONTROLMEDIA. Le tableau comporte des entrées dwMediaNumEntries . Chaque entrée contient un type de média à surveiller, des informations spécifiques au type de média (telles que la durée) et un champ de contrôle multimédia. Si un type de média dans la liste est détecté, l’action de contrôle multimédia correspondante est effectuée sur le flux multimédia de l’appel.

dwMediaNumEntries

Nombre d’entrées dans lpMediaList. TAPI ne valide pas ce paramètre lorsque cette fonction est appelée.

lpToneList

Pointeur vers un tableau avec des entrées de type LINEMEDIACONTROLTONE. Le tableau comporte des entrées dwToneNumEntries . Chaque entrée contient une description d’une tonalité à surveiller, la durée de la tonalité et un champ de contrôle multimédia. Si une tonalité dans la liste est détectée, l’action de contrôle multimédia correspondante est effectuée sur le flux multimédia de l’appel.

dwToneNumEntries

Nombre d’entrées dans lpToneList. TAPI ne valide pas ce paramètre lorsque cette fonction est appelée.

lpCallStateList

Pointeur vers un tableau avec des entrées de type LINEMEDIACONTROLCALLSTATE. Le tableau comporte des entrées dwCallStateNumEntries . Chaque entrée contient un état d’appel et une action de contrôle multimédia.

dwCallStateNumEntries

Nombre d’entrées dans lpCallStateList. 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_INVALADDRESSID, LINEERR_INVALPOINTER, LINEERR_INVALCALLHANDLE, LINEERR_INVALTONELIST, LINEERR_INVALCALLSELECT, LINEERR_NOMEM, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITLIST, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIALIST.

Remarques

Cette fonction retourne zéro (réussite) lorsque le contrôle multimédia est correctement lancé, et non quand un contrôle multimédia prend effet. Le contrôle multimédia en cours est modifié ou est annulé lorsque cette fonction est appelée à nouveau avec des paramètres différents ou des valeurs NULL.

Une seule demande de contrôle multimédia peut être en attente sur un appel à la fois. Une demande remplace toutes les demandes qui peuvent être en suspens.

Selon le fournisseur de services et d’autres activités qui sont en concurrence pour ces ressources, la quantité de détections simultanées qui peuvent être effectuées peut varier au fil du temps. Si les ressources du fournisseur de services sont surcommises, elle retourne LINEERR_RESOURCEUNAVAIL.

Le fait que le contrôle multimédia soit pris en charge par le fournisseur de services est une fonctionnalité d’appareil indiquée dans LINEDEVCAPS.

Chaque fois que TSPI_lineSetMediaControl est appelé, la nouvelle requête remplace tout contrôle multimédia actuellement en vigueur. Si un ou plusieurs des paramètres lpDigitList, lpMediaList, lpToneList et lpCallStateList ont la valeur NULL, le chiffre, le type de média, la tonalité ou le contrôle multimédia déclenché par l’état correspondants est désactivé. Pour modifier uniquement une partie des paramètres de contrôle multimédia tout en laissant les paramètres restants en vigueur, l’application doit appeler TSPI_lineSetMediaControl en fournissant les paramètres précédents pour les parties qui doivent rester en vigueur, et les nouveaux paramètres pour les parties qui doivent être modifiées.