lineSetMediaControl, fonction (tapi.h)

Article
03/04/2024

La fonction 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.

Syntaxe

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Paramètres

hLine

Gérer sur un appareil de ligne ouverte.

dwAddressID

Identificateur d’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.

hCall

Gérer à un appel. L’application doit être propriétaire de l’appel. L’état d’appel de hCall peut être n’importe quel état.

dwSelect

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 est le seul et unique des constantes LINECALLSELECT_.

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 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’élément lpDigitList.

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.

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.

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. Chaque fois que l’appel donné passe à l’un des états d’appel de la liste, l’action de contrôle multimédia correspondante est appelée.

dwCallStateNumEntries

Nombre d’entrées dans lpCallStateList.

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_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITLIST, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIALIST, LINEERR_INVALPOINTER, LINEERR_INVALTONELIST.

Remarques

La fonction lineSetMediaControl est considérée comme réussie si le contrôle multimédia a été correctement lancé, et non quand un contrôle multimédia a pris effet. Le contrôle multimédia en cours est modifié ou est annulé en appelant à nouveau cette fonction avec des paramètres différents ou des valeurs NULL. 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 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.

Si hCall est sélectionné et que l’appel se termine ou que l’application libère son handle, le contrôle multimédia sur cet appel est annulé.

Toutes les applications propriétaires de l’appel sont en principe autorisées à effectuer des demandes de contrôle multimédia sur l’appel. Une seule demande de contrôle multimédia peut être en attente sur un appel dans toutes les applications propriétaires de l’appel. Chaque fois que lineSetMediaControl est appelé, la nouvelle requête remplace tout contrôle multimédia alors en vigueur sur l’appel, qu’il soit défini par l’application appelante ou toute autre application propriétaire.

Selon le fournisseur de services et d’autres activités qui sont en concurrence pour ces ressources, le nombre de détections simultanées pouvant être effectuées peut varier au fil du temps. Si les ressources du fournisseur de services sont sursémises, l’erreur LINEERR_RESOURCEUNAVAIL est retournée.

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