lineConfigDialogEdit, fonction (tapi.h)

Article
08/26/2023

La fonction lineConfigDialogEdit permet au fournisseur de l’appareil de ligne spécifié d’afficher une boîte de dialogue (attachée à hwndOwner de l’application) pour permettre à l’utilisateur de configurer les paramètres liés à l’appareil de ligne.

Syntaxe

LONG lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

Paramètres

dwDeviceID

Identificateur de l’appareil de ligne à configurer.

hwndOwner

Handle à une fenêtre à laquelle la boîte de dialogue doit être attachée. Peut être NULL pour indiquer que toute fenêtre créée pendant la fonction ne doit avoir aucune fenêtre propriétaire.

lpszDeviceClass

Pointeur vers une chaîne terminée par null qui identifie un nom de classe d’appareil. Cette classe d’appareil permet à l’application de sélectionner un sous-écran spécifique d’informations de configuration applicables à cette classe d’appareil. Ce paramètre est facultatif et peut être laissé NULL ou vide, auquel cas la configuration de niveau le plus élevé est sélectionnée.

lpDeviceConfigIn

Pointeur vers la structure de données de configuration opaque retournée par lineGetDevConfig (ou un appel précédent de 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 lineGetDevConfig ou un appel précédent de 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 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 nombre d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarques

Si LINEERR_STRUCTURETOOSMALL est retourné, le membre dwTotalSize de la structure VARSTRING pointée par lpDeviceConfigOut ne spécifie pas suffisamment de mémoire pour contenir l’ensemble de la structure de configuration. Le membre dwNeededSize a été défini sur la quantité requise. Dans la mesure où les entrées utilisateur ont été reflétées dans des informations qui n’ont pas pu être retournées en raison d’un espace insuffisant, ces modifications sont perdues ; Les applications doivent donc allouer la quantité maximale d’espace nécessaire à la classe d’appareil pour retourner sa structure de configuration (pour plus d’informations, consultez Classes d’appareils TAPI).

La fonction lineConfigDialogEdit amène le fournisseur de services à afficher une boîte de dialogue modale (attachée à hwndOwner de l’application) pour permettre à l’utilisateur de configurer les paramètres liés à la ligne spécifiée par dwDeviceID.

Le paramètre lpszDeviceClass permet à l’application de sélectionner 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 lineGetID. Par exemple, si la ligne prend en charge l’API Comm, en passant « COMM » en tant que lpszDeviceClass , le fournisseur affiche les paramètres liés spécifiquement à Comm (ou, au moins, commencez au point correspondant dans une chaîne de boîte de dialogue de configuration à plusieurs niveaux, de sorte que l’utilisateur n’ait pas à « creuser » pour trouver les paramètres qui vous intéressent).

Le paramètre lpszDeviceClass serait « 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 lineConfigDialog est la source des paramètres à modifier et le résultat de la modification. Dans 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ètre à partir de lineConfigDialog. Avec 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, 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 à lineSetDevConfig pour affecter l’appel actuel ou l’appel suivant.