AddPortUI-Funktion (winsplp.h)

Artikel
03/01/2024

Die AddPortUI-Funktion einer Portmonitor-UI-DLL fügt einen Druckerport hinzu, ruft dann Die Informationen zur Portkonfiguration vom Benutzer ab und sendet sie an die Portmonitorserver-DLL.

Syntax

BOOL AddPortUI(
  [in, optional]  PCWSTR pszServer,
  [in]            HWND   hWnd,
                  PCWSTR pszMonitorNameIn,
  [out, optional] PWSTR  *ppszPortNameOut
);

Parameter

[in, optional] pszServer

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die einen Servernamen darstellt, oder NULL , wenn der Drucker lokal ist.

[in] hWnd

Das vom Aufrufer bereitgestellte Handle des Fensters, das als übergeordnetes Element für Dialogfelder verwendet werden soll. Bei NULL sollten keine Dialogfelder angezeigt werden.

pszMonitorNameIn

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Namen des Monitors darstellt. Kann NULL sein.

[out, optional] ppszPortNameOut

Vom Aufrufer bereitgestellter Zeiger auf einen Speicherort, an dem eine Portnamenzeichenfolge empfangen werden soll. Kann NULL sein, in diesem Fall wird kein Name zurückgegeben.

Rückgabewert

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte SetLastError aufgerufen werden, um einen Fehlercode anzugeben, und die Funktion sollte FALSE zurückgeben. Wenn der Vorgang vom Benutzer abgebrochen wird oder nicht unterstützt wird, sollte die Funktion SetLastError(ERROR_CANCELLED) aufrufen und dann FALSE zurückgeben.

Hinweise

Portmonitor-UI-DLLs sind erforderlich, um eine AddPortUI-Funktion zu definieren und die Adresse der Funktion in eine MONITORUI-Struktur einzuschließen.

Der Spooler ruft AddPortUI aus seiner AddPort-Funktion auf. Die ersten drei Argumente, die von AddPortUI empfangen werden, sind die argumente, die von AddPort empfangen werden. (Die AddPort-Funktion wird in der dokumentation Microsoft Windows SDK beschrieben.)

Die Funktion sollte die folgenden Vorgänge ausführen:

Rufen Sie OpenPrinter auf, und geben Sie einen Druckernamen im folgenden Format an:

\\ServerName\,XcvMonitorMonitorName

Dabei sind ServerName und MonitorName die Server- und Monitornamen, die als AddPortUI-Funktionsargumente empfangen werden.

Der Aufruf von OpenPrinter erfordert eine PRINTER_DEFAULTS-Struktur, die in der Windows SDK-Dokumentation beschrieben wird. Der DesiredAccess-Member der Struktur muss auf SERVER_ACCESS_ADMINISTER festgelegt werden. Die pDatatype - und pDevMode-Member können NULL sein.

Dieser Aufruf bewirkt, dass die XcvOpenPort-Funktion der Druckmonitorserver-DLL aufgerufen wird.
Rufen Sie einen Portnamen vom Benutzer ab, indem Sie ein Dialogfeld anzeigen.
Rufen Sie XcvData auf, und geben Sie die folgenden Eingabeargumente an:
- Das von OpenPrinter empfangene Handle
- Der vom Benutzer empfangene Portname
- Eine benutzerdefinierte Datennamenzeichenfolge, z. B. "PortExists"
Dieser Aufruf bewirkt, dass die XcvDataPort-Funktion der Server-DLL aufgerufen wird. Die XcvDataPort-Funktion sollte einen Wert zurückgeben, der angibt, ob der angegebene Portname bereits verwendet wurde. Falls vorhanden, sollte die UI-DLL einen anderen Namen vom Benutzer anfordern und XcvData erneut aufrufen.
Nachdem ein gültiger neuer Portname empfangen wurde, rufen Sie XcvData erneut auf, und geben Sie dabei die folgenden Eingabeargumente an.
- Das von OpenPrinter empfangene Handle
- Der überprüfte Portname, der vom Benutzer empfangen wurde
- Eine Datennamenzeichenfolge von "AddPort"
Dieser Aufruf bewirkt, dass die XcvDataPort-Funktion der Server-DLL erneut aufgerufen wird.
Rufen Sie portkonfigurationsparameter vom Benutzer ab, indem Sie ein Dialogfeld anzeigen.
Rufen Sie XcvData einmal oder mehrmals auf, und geben Sie benutzerdefinierte Datennamenzeichenfolgen an, um jeden Konfigurationsparameter an die Server-DLL zu senden. Jeder XcvData-Aufruf bewirkt, dass die XcvDataPort-Funktion des Servers aufgerufen wird.
Rufen Sie ClosePrinter auf, und geben Sie das von OpenPrinter empfangene Handle an. Dadurch wird die XcvClosePort-Funktion der Server-DLL aufgerufen.