TUISPI_lineConfigDialog-Funktion (tspi.h)

Artikel
03/03/2024

Die funktion TUISPI_lineConfigDialog bewirkt, dass der Anbieter des angegebenen Leitungsgeräts ein modales Dialogfeld als untergeordnetes Fenster von hwndOwner anzeigt, damit der Benutzer Parameter im Zusammenhang mit dem Leitungsgerät konfigurieren kann. Diese Funktion macht die funktion TSPI_lineConfigDialog in Version 2.0 und höher veraltet (unterstützt in Version 1.4 und früher).

Die Implementierung ist optional.

Syntax

LONG TSPIAPI TUISPI_lineConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass
);

Parameter

lpfnUIDLLCallback

Zeiger auf eine Funktion, die die UI-DLL aufrufen kann, um mit der Dienstanbieter-DLL zu kommunizieren, um informationen zu erhalten, die zum Anzeigen des Dialogfelds und zum Senden der aktualisierten Konfiguration an den Dienstanbieter erforderlich sind.

dwDeviceID

Das zu konfigurierende Leitungsgerät.

hwndOwner

Ein Handle für ein übergeordnetes Fenster, in dem das Dialogfeldfenster platziert werden soll.

lpszDeviceClass

Ein Zeiger auf eine NULL-endende Zeichenfolge, die einen Geräteklassennamen identifiziert. Mit dieser Geräteklasse kann der Aufrufer einen bestimmten Unterbildschirm der Konfigurationsinformationen auswählen, die für diese Geräteklasse gelten. Wenn dieser Parameter NULL oder eine leere Zeichenfolge ist, sollte das Konfigurationsdialogfeld der höchsten Ebene ausgewählt werden. Die zulässigen Zeichenfolgen sind identisch mit denen für TSPI_lineGetID. Wenn die Zeile z. B. die Comm-API unterstützt, bewirkt die Übergabe von comm/datamodem als lpszDeviceClass , dass der Anbieter die Parameter anzeigt, die sich speziell auf Comm beziehen (oder zumindest am entsprechenden Punkt in einer Konfigurationsdialogfeldkette mit mehreren Ebenen beginnt, sodass der Benutzer nicht suchen muss, um die gewünschten Parameter zu finden.)

Rückgabewert

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

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Hinweise

Es gibt keine Einschränkung, dass TUISPI_lineConfigDialog nur aufgerufen werden, wenn die Zeile geschlossen wird. Allerdings kann jeder Anbieter eine solche Einschränkung selbst erzwingen. Wenn TUISPI_lineConfigDialog aufgerufen wird, kann der Anbieter den Benutzer mit der Meldung "Die Zeile wird von einer oder mehreren Anwendungen verwendet. Sie dürfen die Zeilenkonfiguration nicht ändern, während die Zeile verwendet wird" (und die Fehlermeldung LINEERR_INUSE zurückgeben). Einige Konfigurationen können jedoch "im Handumdrehen" geändert werden, insbesondere solche, die sich auf Medientypen beziehen (z. B. das Modemfehlersteuerungsprotokoll), insbesondere wenn dieser Medientyp derzeit nicht verwendet wird. Der Anbieter kann zulassen, dass diese Optionen geändert werden, während die Zeile geöffnet ist.

Benutzer sollten nichts ändern dürfen, das mit LINEDEVCAPS oder LINEADDRESSCAPS zurückgegebene Werte ändert, ohne die Zeile zuerst als Signal zu schließen, dass Anwendungen Funktionen aufrufen müssen, die diese Strukturen zurückgeben, um genaue Informationen zu erhalten.