XcvDataPort-Funktion (winsplp.h)

Artikel
02/07/2025

Die XcvDataPort-Funktion eines Portmonitor-Servers empfängt Informationen und gibt Informationen an die UI-DLL des Portmonitors 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, abgerufen durch Aufrufen OpenPrinter- (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 in Byte, auf den pInputData-verweist.

[out] pOutputData

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

cbOutputData

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

[out] pcbOutputNeeded

Vom Aufrufer bereitgestellter Zeiger auf eine Position, um die minimale Größe in Byte zu empfangen, 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_-präfixer Win32-Fehlercode zurückgegeben werden. Die UI-DLL des Druckmonitors empfängt diesen Wert in der pdwStatus- Speicherort, der für XcvData-angegeben ist.

Bemerkungen

Portmonitor-Server-DLLs sind erforderlich, um eine XcvDataPort--Funktion zu definieren, damit sie Informationen von einer Portmonitor-UI-DLL empfangen und Informationen 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 XcvDataPortnicht vorhanden ist.)

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

Datennamenzeichenfolge	Operation
L"AddPort"	Alle zum Hinzufügen eines Ports erforderlichen Informationen wurden gesendet. Die Funktion sollte Vorgänge ausführen, die erforderlich sind, um den angegebenen Port hinzuzufügen, einschließlich des Schreibens des Portnamens in der Registrierung unter dem Ports-Schlüssel. Der pInputData--Parameter verweist auf eine Zeichenfolge mit NULL-beendetem Portnamen. Wenn die Funktion ERROR_SUCCESS zurückgibt, markiert der Spooler den Port als hinzugefügt. Diese Zeichenfolge wird von der Druckmonitor-UI-DLL innerhalb der AddPortUI--Funktion angegeben.
L"DeletePort"	Alle zum Löschen eines Ports erforderlichen Informationen 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 Zeichenfolge mit NULL-beendetem Portnamen. Wenn die Funktion ERROR_SUCCESS zurückgibt, markiert der Spooler den Port als gelöscht. Diese Zeichenfolge wird von der Druckmonitor-UI-DLL 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 durch den Druckspooler angegeben, wenn eine Anwendung das Microsoft Windows SDK AddPort--Funktion aufruft.

In der Regel wird die Funktion geschrieben, um zusätzliche, angepasste Zeichenfolgen zu erkennen, die von der UI-DLL innerhalb ihrer AddPortUI-, ConfigurePortUI-und DeletePortUI--Funktionen gesendet werden. Diese Zeichenfolgen können Befehle darstellen, die aktuelle Konfigurationswerte von der Server-DLL anfordern oder neue Werte liefern. Ihre XcvDataPort--Funktion erkennt beispielsweise die Zeichenfolge "GetTransmissionRetryTimeout", die Ihre UI-DLL an Ihre Server-DLL senden könnte, um den aktuell gespeicherten Wiederholungs-Timeoutwert anzufordern. Oder Sie können einen Satz von Zeichenfolgen definieren, die gesendet werden müssen, bevor "AddPort" oder "DeletePort" gesendet wird, wobei die Zeichenfolgen verwendet werden, um Informationen anzugeben, die den Port angeben, der hinzugefügt oder gelöscht werden soll.

Bei einem bestimmten pszDataName Zeichenfolgen- und Eingabepuffer kann XcvDataPort- zuerst mit einem cbOutputData Wert null aufgerufen werden. Die Funktion sollte eine erforderliche Puffergröße in pcbOutputNeedededzusammen mit einem Rückgabewert von ERROR_INSUFFICIENT_BUFFER zurückgeben. Der Aufrufer kann den in pcbOutputNeedededed empfangenen Wert verwenden, um einen Ausgabepuffer einer angemessenen Größe zuzuweisen, und kann dann XcvDataPort erneut aufrufen, diesmal die zugeordnete Puffergröße in cbOutputData.

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 pszDataName Parameter verweist. Wenn diese Zeichenfolge einen administrativen Vorgang darstellt (in der Regel hinzufügen, löschen oder konfigurieren eines Ports), sollte die XcvDataPort-funktion die gewährte Zugriffsmaske vergleichen, die zuvor von der XcvOpenPort--Funktion mit SERVER_ACCESS_ADMINISTER empfangen wurde. 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 des Inhalts dieses Puffers durch. Der Monitor kann keine Annahmen über die Gültigkeit dieser Daten machen, die aus einer schädlichen Anwendung stammen können.

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