fonction TSPI_lineConfigDialogEdit (tspi.h)
La fonction TSPI_lineConfigDialogEdit est obsolète. Les fournisseurs de services TAPI version 1.4 ou antérieure peuvent implémenter cette fonction TSPI. TAPI version 2.0 ou ultérieure implémentent TUISPI_lineConfigDialogEdit.
La fonction TSPI_lineConfigDialogEdit permet au fournisseur de l’appareil de ligne spécifié d’afficher une boîte de dialogue modale sous la forme d’une fenêtre enfant de hwndOwner pour permettre à l’utilisateur de configurer des paramètres liés à l’appareil de ligne.
Syntaxe
LONG TSPIAPI TSPI_lineConfigDialogEdit(
DWORD dwDeviceID,
HWND hwndOwner,
LPCSTR lpszDeviceClass,
LPVOID const lpDeviceConfigIn,
DWORD dwSize,
LPVARSTRING lpDeviceConfigOut
);
Paramètres
dwDeviceID
Périphérique de ligne à configurer.
hwndOwner
Handle à 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 des 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 TSPI_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 TSPI_lineConfigDialogEdit.
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 de la structure VARSTRING est défini sur STRINGFORMAT_BINARY. Avant d’appeler lineGetDevConfig (ou un appel futur de lineConfigDialogEdit), l’application doit définir le membre dwTotalSize de cette structure pour indiquer la quantité de mémoire disponible pour 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
Cette fonction permet au fournisseur de services d’afficher une boîte de dialogue modale (attachée à hwndOwner) pour permettre à l’utilisateur de configurer les paramètres liés à la ligne spécifiée par dwDeviceID.
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 entraîne l’affichage des paramètres liés spécifiquement à Comm (ou, au moins, de commencer 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 d’intérêt).
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 TSPI_lineConfigDialog est la source des paramètres à modifier et le résultat de la modification. Dans TSPI_lineConfigDialog, les paramètres modifiés sont ceux en cours d’utilisation 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 à partir de TSPI_lineConfigDialog. Avec TSPI_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, TSPI_lineConfigDialogEdit permet à une application de fournir à l’utilisateur la possibilité de configurer des paramètres pour les appels futurs sans avoir d’impact sur un appel actif. Toutefois, la sortie de cette fonction peut être transmise à TSPI_lineSetDevConfig pour affecter l’appel actuel ou l’appel suivant.
Pour la compatibilité descendante, cette fonction n’est pas exportée par les anciens fournisseurs de services. TAPI détecte cette condition et signale LINEERR_OPERATIONUNAVAIL si une application tente d’appeler cette fonction sur un fournisseur plus ancien.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Windows |
| En-tête | tspi.h |