TUISPI_lineConfigDialogEdit, fonction (tspi.h)

Article
08/26/2023

La fonction TUISPI_lineConfigDialogEdit permet au fournisseur de l’appareil de ligne spécifié d’afficher une boîte de dialogue modale en tant que fenêtre enfant de hwndOwner pour permettre à l’utilisateur de configurer les paramètres liés à l’appareil de ligne. Cette fonction rend la fonction TSPI_lineConfigDialogEdit obsolète dans les versions 2.0 et ultérieures (prises en charge dans les versions 1.4 et antérieures).

L’implémentation est facultative.

Syntaxe

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass,
  LPVOID const      lpDeviceConfigIn,
  DWORD             dwSize,
  LPVARSTRING       lpDeviceConfigOut
);

Paramètres

lpfnUIDLLCallback

Pointeur vers une fonction que la DLL d’interface utilisateur peut appeler pour communiquer avec la DLL du fournisseur de services afin d’obtenir les informations nécessaires à l’affichage de la boîte de dialogue.

dwDeviceID

Périphérique de ligne à configurer.

hwndOwner

Handle d’une fenêtre à laquelle la boîte de dialogue doit être attachée.

lpszDeviceClass

Pointeur vers une chaîne Unicode terminée par null qui identifie un nom de classe d’appareil. Cette classe d’appareil permet à l’appelant de sélectionner un sous-écran spécifique d’informations de configuration applicables à cette classe d’appareil. Si ce paramètre a la valeur NULL ou pointe vers une chaîne vide, la configuration de niveau le plus élevé est sélectionnée. Les chaînes autorisées sont les mêmes que pour TSPI_lineGetID.

lpDeviceConfigIn

Pointeur vers la structure de données de configuration opaque retournée par TSPI_lineGetDevConfig (ou un appel précédent de TUISPI_lineConfigDialogEdit) dans la partie variable de la structure VARSTRING .

dwSize

Nombre d’octets dans la structure pointée vers lpDeviceConfigIn. Cette valeur est retournée dans le membre dwStringSize de la structure VARSTRING retournée par TSPI_lineGetDevConfig ou un appel précédent de TUISPI_lineConfigDialogEdit.

Note Si les paramètres de taille dans 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 .

lpDeviceConfigOut

Pointeur vers l’emplacement de mémoire de type VARSTRING où la structure de configuration de l’appareil est retournée. Une fois la demande terminée, cet emplacement est rempli avec la configuration de l’appareil. Le membre dwStringFormat dans la structure VARSTRING est défini sur STRINGFORMAT_BINARY. Avant d’appeler lineGetDevConfig (ou un appel ultérieur de lineConfigDialogEdit), l’application doit définir le membre dwTotalSize de cette structure pour indiquer la quantité de mémoire disponible à TAPI pour retourner des informations.

Valeur retournée

Retourne zéro si la demande réussit ou un numéro d’erreur si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM.

Remarques

Le paramètre lpszDeviceClass sélectionne un sous-écran spécifique d’informations de configuration applicables à la classe d’appareil qui intéresse l’utilisateur ; les chaînes autorisées sont les mêmes que pour TSPI_lineGetID. Par exemple, si la ligne prend en charge l’API Comm, le passage de comm/datamodem en tant que lpszDeviceClass amène le fournisseur à afficher les paramètres liés spécifiquement à Comm (ou, au moins, à démarrer au point correspondant dans une chaîne de boîte de dialogue de configuration à plusieurs niveaux, de sorte que l’utilisateur n’a pas à « creuser » pour trouver les paramètres intéressants).

Le paramètre lpszDeviceClass est « tapi/line », « » ou NULL pour que le fournisseur affiche la configuration de niveau le plus élevé pour la ligne.

La différence entre cette fonction et TUISPI_lineConfigDialog est la source des paramètres à modifier et le résultat de la modification. Dans TUISPI_lineConfigDialog, les paramètres modifiés sont ceux actuellement utilisés sur l’appareil (ou définis pour être utilisés lors de l’appel suivant), et toutes les modifications apportées ont (dans la mesure du possible) un impact immédiat sur toute connexion active ; En outre, l’application doit utiliser lineGetDevConfig pour extraire le résultat des modifications de paramètres de TUISPI_lineConfigDialog. Avec TUISPI_lineConfigDialogEdit, les paramètres à modifier sont transmis à partir de l’application et les résultats sont retournés à l’application, sans impact sur les connexions actives ; les résultats de la modification sont retournés avec cette fonction, et l’application n’a pas besoin d’appeler lineGetDevConfig. Ainsi, TUISPI_lineConfigDialogEdit permet à une application de fournir à l’utilisateur la possibilité de configurer des paramètres pour les appels futurs sans avoir d’impact sur les appels actifs. Toutefois, la sortie de cette fonction peut être passée à TSPI_lineSetDevConfig pour affecter l’appel actuel ou l’appel suivant.

Pour la compatibilité descendante, cette fonction n’est pas exportée par les fournisseurs de services plus anciens. TAPI détecte cette condition et signale LINEERR_OPERATIONUNAVAIL si une application tente d’appeler cette fonction sur un fournisseur plus ancien.