TUISPI_lineConfigDialog, fonction (tspi.h)

Article
08/26/2023

La fonction TUISPI_lineConfigDialog 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 au périphérique de ligne. Cette fonction rend la fonction TSPI_lineConfigDialog 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_lineConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass
);

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 et à l’envoi de la configuration mise à jour au fournisseur de services.

dwDeviceID

Périphérique de ligne à configurer.

hwndOwner

Handle vers une fenêtre parente dans laquelle la fenêtre de boîte de dialogue doit être placée.

lpszDeviceClass

Pointeur vers une chaîne 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 une chaîne vide, la boîte de dialogue de configuration de niveau le plus élevé doit être sélectionnée. 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, afin que l’utilisateur n’ait pas à effectuer de recherche pour trouver les paramètres souhaités.)

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_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarques

Il n’existe aucune restriction selon laquelle TUISPI_lineConfigDialog être appelée uniquement lorsque la ligne est fermée. Toutefois, chaque fournisseur peut imposer une telle restriction lui-même. Quand TUISPI_lineConfigDialog est appelé, le fournisseur peut alerter l’utilisateur avec le message « La ligne est utilisée par une ou plusieurs applications. Vous ne pouvez pas modifier la configuration de ligne pendant l’utilisation de la ligne » (et renvoyer le message d’erreur LINEERR_INUSE). Toutefois, certaines configurations peuvent être modifiées « à la volée », en particulier celles liées aux types de médias (comme le protocole de contrôle d’erreur du modem), en particulier lorsque ce type de média n’est pas actuellement utilisé. Le fournisseur peut autoriser la modification de ces options lorsque la ligne est ouverte.

Les utilisateurs ne doivent pas être autorisés à modifier quoi que ce soit qui modifie les valeurs retournées avec LINEDEVCAPS ou LINEADDRESSCAPS sans d’abord fermer de force la ligne comme un signal indiquant que les applications doivent appeler des fonctions qui retournent ces structures pour avoir des informations précises.