lineConfigDialogEdit-Funktion (tapi.h)

Artikel
08/26/2023

Die lineConfigDialogEdit-Funktion bewirkt, dass der Anbieter des angegebenen Zeilengeräts ein Dialogfeld anzeigt (das an hwndOwner der Anwendung angefügt ist), damit der Benutzer Parameter im Zusammenhang mit dem Zeilengerät konfigurieren kann.

Syntax

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

Parameter

dwDeviceID

Bezeichner des zu konfigurierenden Leitungsgeräts.

hwndOwner

Handle mit einem Fenster, an das das Dialogfeld angefügt werden soll. Kann NULL sein, um anzugeben, dass jedes während der Funktion erstellte Fenster kein Besitzerfenster haben sollte.

lpszDeviceClass

Zeiger auf eine NULL-beendete Zeichenfolge, die einen Geräteklassennamen identifiziert. Mit dieser Geräteklasse kann die Anwendung einen bestimmten Unterbildschirm von Konfigurationsinformationen auswählen, die für diese Geräteklasse gelten. Dieser Parameter ist optional und kann NULL oder leer bleiben. In diesem Fall wird die Konfiguration der höchsten Ebene ausgewählt.

lpDeviceConfigIn

Zeiger auf die undurchsichtige Konfigurationsdatenstruktur, die von lineGetDevConfig (oder einem vorherigen Aufruf von lineConfigDialogEdit) im Variablenteil der VARSTRING-Struktur zurückgegeben wurde.

dwSize

Anzahl der Bytes in der Struktur, auf die von lpDeviceConfigIn verwiesen wird. Dieser Wert wird im dwStringSize-Member in der VARSTRING-Struktur zurückgegeben, die von lineGetDevConfig oder einem vorherigen Aufruf von lineConfigDialogEdit zurückgegeben wird.

lpDeviceConfigOut

Zeiger auf den Speicherspeicherort des Typs VARSTRING , an dem die Gerätekonfigurationsstruktur zurückgegeben wird. Nach erfolgreichem Abschluss der Anforderung wird dieser Speicherort mit der Gerätekonfiguration gefüllt. Das dwStringFormat-Element in der VARSTRING-Struktur ist auf STRINGFORMAT_BINARY festgelegt. Vor dem Aufrufen von lineGetDevConfig (oder einem zukünftigen Aufruf von lineConfigDialogEdit) sollte die Anwendung den dwTotalSize-Member dieser Struktur festlegen, um die Menge an Arbeitsspeicher anzugeben, der TAPI zum Zurückgeben von Informationen zur Verfügung steht.

Rückgabewert

Gibt null zurück, wenn die Anforderung erfolgreich ist, oder eine negative Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

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

Hinweise

Wenn LINEERR_STRUCTURETOOSMALL zurückgegeben wird, gibt das dwTotalSize-Element der VARSTRING-Struktur , auf die von lpDeviceConfigOut verwiesen wird, nicht genügend Arbeitsspeicher an, um die gesamte Konfigurationsstruktur zu enthalten. Der dwNeededSize-Member wurde auf den erforderlichen Betrag festgelegt. Soweit Benutzereinträge in Informationen widergespiegelt wurden, die aufgrund des unzureichenden Speicherplatzes nicht zurückgegeben werden konnten, gehen diese Änderungen verloren; Anwendungen sollten daher den maximalen Speicherplatz zuweisen, der von der Geräteklasse benötigt wird, um die Konfigurationsstruktur zurückzugeben (weitere Informationen finden Sie unter TAPI-Geräteklassen).

Die lineConfigDialogEdit-Funktion bewirkt, dass der Dienstanbieter ein modales Dialogfeld anzeigt (das an hwndOwner der Anwendung angefügt ist), damit der Benutzer Parameter konfigurieren kann, die sich auf die von dwDeviceID angegebene Zeile beziehen.

Mit dem Parameter lpszDeviceClass kann die Anwendung einen bestimmten Unterbildschirm der Konfigurationsinformationen auswählen, die für die Geräteklasse gelten, an der der Benutzer interessiert ist. die zulässigen Zeichenfolgen sind mit denen für lineGetID identisch. Wenn die Zeile z. B. die Comm-API unterstützt, bewirkt die Übergabe von "COMM" als lpszDeviceClass , dass der Anbieter die Speziell für Comm relevanten Parameter anzeigt (oder zumindest an dem entsprechenden Punkt in einer Konfigurationsdialogfeldkette mit mehreren Ebenen beginnt, sodass der Benutzer nicht "graben" muss, um die relevanten Parameter zu finden).

Der parameter lpszDeviceClass würde "tapi/line", "" oder NULL lauten , damit der Anbieter die Konfiguration der höchsten Ebene für die Zeile anzeigt.

Der Unterschied zwischen dieser Funktion und lineConfigDialog ist die Quelle der zu bearbeitenden Parameter und das Ergebnis der Bearbeitung. In lineConfigDialog sind die bearbeiteten Parameter diejenigen, die derzeit auf dem Gerät verwendet werden (oder für die Verwendung beim nächsten Aufruf festgelegt sind), und alle vorgenommenen Änderungen haben (soweit möglich) unmittelbare Auswirkungen auf jede aktive Verbindung; Außerdem muss die Anwendung lineGetDevConfig verwenden, um das Ergebnis von Parameteränderungen aus lineConfigDialog abzurufen. Mit lineConfigDialogEdit werden die zu bearbeitenden Parameter von der Anwendung übergeben, und die Ergebnisse werden an die Anwendung zurückgegeben, ohne auswirkungen auf aktive Verbindungen. die Ergebnisse der Bearbeitung werden mit dieser Funktion zurückgegeben, und die Anwendung muss lineGetDevConfig nicht aufrufen. Daher ermöglicht lineConfigDialogEdit einer Anwendung, dem Benutzer die Möglichkeit zu bieten, Parameter für zukünftige Aufrufe einzurichten, ohne auswirkungen auf einen aktiven Aufruf zu haben. Die Ausgabe dieser Funktion kann jedoch an lineSetDevConfig übergeben werden, um den aktuellen oder nächsten Aufruf zu beeinflussen.