fonction TSPI_lineSetDevConfig (tspi.h)

Article
03/03/2024

La fonction TSPI_lineSetDevConfig restaure la configuration d’un appareil associé un-à-un à l’appareil de ligne à partir d’une structure de données obtenue précédemment à l’aide de TSPI_lineGetDevConfig. Le contenu de cette structure de données est spécifique à la ligne [fournisseur de services] et à la classe d’appareil.

Syntaxe

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

Paramètres

dwDeviceID

Périphérique de ligne à configurer.

lpDeviceConfig

Pointeur vers la structure de données de configuration retournée dans la partie variable de la structure VARSTRING par TSPI_lineGetDevConfig.

dwSize

Nombre d’octets dans la structure pointée vers lpDeviceConfig. Cette valeur est retournée dans le membre dwStringSize de la structure VARSTRING retournée par TSPI_lineGetDevConfig.

Note Si les paramètres de taille de la structure ne sont pas corrects, il est possible que les données soient remplacées. Pour plus d’informations sur la définition des tailles de structure, consultez la rubrique allocation de mémoire .

lpszDeviceClass

Pointeur vers une chaîne Unicode terminée par null qui spécifie la classe d’appareil de l’appareil dont la configuration doit être restauré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 « ligne » (autrement dit, lorsque 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_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER.

Remarques

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

Le fournisseur de services retourne LINEERR_INVALPARAM si les informations contenues dans la structure pointée par lpDeviceConfig ne sont pas valides pour cet appareil.

Le fournisseur de services retourne LINEERR_INVALLINESTATE si la configuration de l’appareil ne peut pas être modifiée dans l’état de ligne actuel. La ligne peut être utilisée par une autre application.

Cette fonction peut être utilisée pour restaurer la configuration d’un appareil associé un-à-un à l’appareil de ligne à partir d’une structure de données précédemment récupérée auprès du fournisseur de services à l’aide de la fonction TSPI_lineGetDevConfig . Le paramètre lpszDeviceClass sélectionne parmi les différentes classes d’appareils dont la configuration doit être restauré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 autorise généralement la classe d’appareil tapi/line sous cette fonction. Il restaure les paramètres qui ont une étendue « ligne », tels que la liste des adresses dans cette ligne et la liste des périphériques matériels physiques tels que les ports COMM correspondant aux adresses ou le nombre maximal d’appels simultanés (s’il est configurable).

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 est ambiguë. Une exception peut être faite pour les classes d’appareil spécifiques à l’appel ou à l’adresse dans les cas où des informations de configuration de classe s’appliquent à l’ensemble de l’étendue de l’appareil de ligne, telles que les valeurs par défaut initiales.

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 à plusieurs adresses et à appels multiples, seul un sous-ensemble de fournisseurs de services les prend en charge. Les programmes d’application 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 mettent en œuvre 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 à instance’étendue plutôt qu’à l’étendue de la classe. L’API multimédia de haut niveau doit fournir ses propres fonctions pour configurer des instances spécifiques à un appel ou à une 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 ces informations temporaires qui ont été définies ou récupérées via TSPI_lineGetDevConfig peuvent revenir à des 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 passée à cette fonction est spécifique à l’API de classe de ligne et d’appareil, n’est pas documenté et n’est pas défini. La structure passée à 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 à partir d’un TSPI_lineGetDevConfig précédent pour obtenir 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 case activée cette structure de données à des fins de cohérence afin de se prémunir contre les défaillances dues à la transmission d’informations incompatibles par une application cliente.

Note Certains fournisseurs de services peuvent autoriser la configuration à être définie pendant qu’un appareil est en cours d’utilisation, et d’autres non.