XcvDataPort-Funktion (winsplp.h)

Artikel
03/13/2023

Die XcvDataPort-Funktion einer Portmonitorserver-DLL empfängt Informationen von der UI-DLL des Portmonitors und gibt Informationen zurück.

Syntax

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

Parameter

[in] hXcv

Vom Anrufer bereitgestellter Druckerhandle, der durch Aufrufen von OpenPrinter abgerufen wird (in der Microsoft Windows SDK-Dokumentation beschrieben). Dieses Handle wird von der XcvOpenPort-Funktion erstellt und zurückgegeben.

[in] pszDataName

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Namen der angeforderten Daten darstellt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] pInputData

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, der Eingabedaten enthält.

cbInputData

Vom Aufrufer bereitgestellte Größe des Puffers, auf den pInputData verweist, in Bytes.

[out] pOutputData

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer zum Empfangen von Ausgabedaten.

cbOutputData

Vom Aufrufer bereitgestellte Größe des Puffers, auf den pOutputData verweist, in Bytes.

[out] pcbOutputNeeded

Vom Aufrufer bereitgestellter Zeiger auf einen Speicherort zum Empfangen der Mindestgröße in Bytes, die für den Puffer erforderlich ist, auf den pOutputData verweist.

Rückgabewert

Wenn der Vorgang erfolgreich ist, sollte diese Funktion ERROR_SUCCESS zurückgeben. Andernfalls sollte ein ERROR_ Win32-Fehlercode zurückgegeben werden. Die DLL der Druckmonitor-Benutzeroberfläche empfängt diesen Wert am für XcvData angegebenen Speicherort pdwStatus.

Hinweise

Portmonitorserver-DLLs sind erforderlich, um eine XcvDataPort-Funktion zu definieren, damit sie Informationen von einer Portmonitor-UI-DLL empfangen und an diese zurückgeben können. Die Adresse der Funktion muss in einer MONITOR2-Struktur enthalten sein.

Die XcvDataPort-Funktion wird von der XcvData-Funktion des Spoolers aufgerufen. Die Funktionsparameter für XcvDataPort und XcvData sind nahezu identisch. (XcvData verfügt über einen zusätzlichen Parameter, pdwStatus, der in XcvDataPort nicht vorhanden ist.)

Die Zeichenfolge, auf die von pszDataName verwiesen wird, gibt den auszuführenden Vorgang an. Die Funktion muss die folgenden Datennamenzeichenfolgen erkennen:

Datennamenzeichenfolge	Vorgang
L"AddPort"	Alle Informationen, die zum Hinzufügen eines Ports benötigt werden, wurden gesendet. Die Funktion sollte Vorgänge ausführen, die zum Hinzufügen des angegebenen Ports erforderlich sind, einschließlich des Schreibens des Portnamens in der Registrierung unter dem Portschlüssel. Der pInputData-Parameter verweist auf eine NULL-endende Portnamenzeichenfolge. Wenn die Funktion ERROR_SUCCESS zurückgibt, markiert der Spooler den Port als hinzugefügt. Diese Zeichenfolge wird von der DLL der Drucküberwachungs-UI innerhalb der AddPortUI-Funktion angegeben.
L"DeletePort"	Alle Informationen, die zum Löschen eines Ports benötigt werden, wurden gesendet. Die Funktion sollte Vorgänge ausführen, die zum Löschen des angegebenen Ports erforderlich sind, einschließlich des Entfernens des Portnamens aus dem Ports-Schlüssel der Registrierung. Der pInputData-Parameter verweist auf eine NULL-endende Portnamenzeichenfolge. Wenn die Funktion ERROR_SUCCESS zurückgibt, markiert der Spooler den Port als gelöscht. Diese Zeichenfolge wird von der DLL der Drucküberwachungs-UI innerhalb der DeletePortUI-Funktion angegeben.
L"MonitorUI"	Die Funktion sollte pOutputData verwenden, um den Namen der zugeordneten Portmonitor-UI-DLL zurückzugeben. Diese Zeichenfolge wird vom Druckspooler angegeben, wenn eine Anwendung die Microsoft Windows SDK AddPort-Funktion aufruft.

In der Regel wird die Funktion geschrieben, um zusätzliche benutzerdefinierte Zeichenfolgen zu erkennen, die von der UI-DLL aus den Funktionen AddPortUI, ConfigurePortUI und DeletePortUI gesendet werden. Diese Zeichenfolgen können Befehle darstellen, die aktuelle Konfigurationswerte von der Server-DLL anfordern oder neue Werte liefern. Beispielsweise erkennt Ihre XcvDataPort-Funktion möglicherweise die Zeichenfolge "GetTransmissionRetryTimeout", die Ihre UI-DLL an Ihre Server-DLL senden könnte, um den aktuell gespeicherten Timeoutwert für die Übertragungswiebelung anzufordern. Alternativ können Sie eine Reihe von Zeichenfolgen definieren, die gesendet werden müssen, bevor "AddPort" oder "DeletePort" gesendet wird, wobei die Zeichenfolgen verwendet werden, um Informationen zur Identifizierung des hinzuzufügenden oder zu löschenden Ports anzugeben.

Für eine bestimmte pszDataName-Zeichenfolge und einen Eingabepuffer kann XcvDataPort zuerst mit dem cbOutputData-Wert von 0 aufgerufen werden. Die Funktion sollte eine erforderliche Puffergröße in pcbOutputNeeded zurückgeben, zusammen mit einem Rückgabewert von ERROR_INSUFFICIENT_BUFFER. Der Aufrufer kann den in pcbOutputNeeded empfangenen Wert verwenden, um einen Ausgabepuffer von angemessener Größe zuzuweisen, und kann dann XcvDataPort erneut aufrufen, wobei dieses Mal die zugeordnete Puffergröße in cbOutputData angegeben wird.

Die XcvDataPort-Funktion muss alle Eingabeargumente überprüfen. Insbesondere muss die Funktion Folgendes ausführen:

Überprüfen Sie den Inhalt der Zeichenfolge, auf die der parameter pszDataName verweist. Wenn diese Zeichenfolge einen administrativen Vorgang darstellt (in der Regel ein Hinzufügen, Löschen oder Konfigurieren eines Ports), sollte die XcvDataPort-Funktion die gewährte Zugriffsmaske vergleichen, die zuvor von der XcvOpenPort-Funktion empfangen wurde, mit SERVER_ACCESS_ADMINISTER. Wenn der Vergleich fehlschlägt, muss XcvDataPort ERROR_ACCESS_DENIED zurückgeben.
Überprüfen Sie den Inhalt des Puffers, auf den der pInputData-Parameter verweist. Wenn der Spooler die XcvOpenPort-Funktion aufruft, führt er keine Überprüfung für den Inhalt dieses Puffers durch. Der Monitor kann keine Annahmen über die Gültigkeit dieser Daten machen, die von einer schädlichen Anwendung stammen können.

Wenn Sie einen Portmonitor schreiben, der mit TCPMON kommuniziert, lesen Sie TCPMON Xcv-Schnittstelle.