fonction TSPI_lineGetDevConfig (tspi.h)

Article
08/26/2023

La fonction TSPI_lineGetDevConfig retourne un objet de structure de données, dont le contenu est spécifique à la ligne (fournisseur de services) et à la classe d’appareil, ce qui donne la configuration actuelle d’un appareil associé un-à-un à l’appareil de ligne.

Syntaxe

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

Paramètres

dwDeviceID

Périphérique de ligne à configurer.

lpDeviceConfig

Pointeur vers une structure de données de type VARSTRING où la structure de configuration de l’appareil associé est retournée. Une fois la demande terminée, le fournisseur de services remplit cette structure de données avec la configuration de l’appareil. Le membre dwStringFormat de la structure VARSTRING doit être défini sur STRINGFORMAT_BINARY. Si le membre dwTotalSize de la structure VARSTRING pointée par le paramètre lpDeviceConfig est supérieur ou égal à la taille de la partie fixe de la structure, le fournisseur de services définit le membre dwNeededSize à la taille requise et retourne zéro.

lpszDeviceClass

Pointeur vers une chaîne Unicode terminée par null qui spécifie la classe d’appareil de l’appareil dont la configuration est demandée. Les chaînes de classe d’appareil valides sont les mêmes que celles spécifiées pour la fonction TSPI_lineGetID lorsqu’elle est appliquée à un appareil de ligne (dwSelect a la valeur LINECALLSELECT_LINE).

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_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Remarques

L’état de l’appel est spécifique à l’appareil.

Cette fonction peut être utilisée pour récupérer une structure de données du fournisseur de services qui spécifie la configuration d’un appareil associé un-à-un à l’appareil de ligne. Le paramètre lpszDeviceClass sélectionne parmi les différentes classes d’appareils dont la configuration doit être récupérée. L’ensemble des classes prises en charge est limité à ceux dont les appareils correspondent un à un avec l’appareil de ligne. Pour plus d’informations sur les classes d’appareil courantes, consultez Classes d’appareil TSPI.

Un fournisseur de services doit généralement autoriser la classe d’appareil tapi/ligne sous cette fonction. Il récupère les paramètres qui ont une étendue « ligne », tels que la liste des adresses dans cette ligne, la liste des périphériques matériels physiques tels que les ports COMM correspondant aux adresses, le nombre maximal d’appels simultanés (s’il est configurable) et ainsi de suite.

En général, cette fonction n’autorise pas les classes d’appareil liées aux médias, telles que mci waveaudio, wave de bas niveau ou les classes d’appareil datamodem, car elles s’appliquent généralement à un appel particulier ou à une adresse particulière. Étant donné qu’il peut y avoir plusieurs de ces appareils par ligne, l’identification de l’appel ou de l’adresse particulière simplement par le paramètre d’identificateur d’appareil de ligne dans cette fonction serait ambiguë. Une exception peut être faite pour les classes d’appareil spécifiques à l’appel ou à l’adresse dans les cas où il existe des informations de configuration de classe qui s’appliquent à l’ensemble de l’étendue de l’appareil de ligne, telles que les valeurs par défaut initiales, etc.

Il existe plusieurs raisons pour lesquelles la prise en charge exceptionnelle des classes d’appareils spécifiques à l’appel et à l’adresse n’est que d’une valeur limitée dans le cadre de cette fonction. Tout d’abord, étant donné que ces classes peuvent être ambiguës sur les fournisseurs de services à adresses multiples/appels multiples, seul un sous-ensemble de fournisseurs de services les prend en charge. Les applications ne sont pas susceptibles d’ajouter une dépendance spécifique à l’appareil sur l’inclusion de ces classes dans cette fonction. Deuxièmement, à mesure que des « classes » multimédias de niveau supérieur apparaissent qui implémentent des protocoles de haut niveau, tels que l’accès au système de fichiers rendez-vous en termes d’API de transport de bas niveau, la configuration de ces classes tend vers l’étendue « instance » au lieu de l’étendue « classe ». L’API multimédia de haut niveau doit fournir ses propres fonctions pour configurer des instances spécifiques à l’appel ou à l’adresse.

Quel que soit le type d’appareils et les classes d’appareils pris en charge par cette fonction, elle peut affecter deux types d’informations de configuration : permanentes et temporaires. Les informations permanentes survivent à différentes « ouvertures » de la ligne, et même à différents « inits » du fournisseur de services lui-même. Les informations temporaires survivent uniquement au sein d’un « ouvert » unique de la ligne. Lorsque la ligne est fermée, toutes les informations temporaires qui ont été récupérées ou définies via TSPI_lineSetDevConfig peuvent revenir aux valeurs par défaut ou non définies. L’appelant ne peut récupérer de manière fiable toute configuration temporaire qu’à l’aide d’une séquence telle que TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. L’appelant peut définir de manière fiable les informations de configuration temporaires récupérées par une telle séquence via une séquence telle que TSPI_lineOpen, TSPI_lineSetDevConfig. La partie temporaire de la configuration reste stable uniquement jusqu’au TSPI_lineConfigDialog, TSPI_lineSetDevConfig ou TSPI_lineClose suivant. Le fournisseur de services doit s’occuper du stockage de toute partie permanente de la configuration, généralement dans un fichier .ini, et de le recharger chaque fois que le fournisseur de services est initialisé.

Le format exact des données contenues dans la structure retournée par cette fonction est spécifique à la ligne et à l’API de classe d’appareil, n’est pas documenté et n’est pas défini. La structure retournée par cette fonction ne peut pas être directement accessible ou manipulée par l’application, mais peut uniquement être stockée intacte et utilisée ultérieurement dans TSPI_lineSetDevConfig pour restaurer les paramètres. La structure ne peut pas nécessairement être transmise à d’autres appareils, même de la même classe d’appareil (même si cela peut fonctionner dans certains cas, il n’est pas garanti). Un fournisseur de services doit placer des éléments dans la structure de données pour lui permettre de vérifier la cohérence afin de se prémunir contre les défaillances dues à la transmission d’informations incompatibles par une application cliente.