WritePort-Funktion (winsplp.h)

Artikel
03/01/2024

Die Funktion eines WritePort Portmonitors schreibt Daten in einen Druckeranschluss.

Syntax

BOOL WritePort(
  _In_  HANDLE  hPort,
  _In_  LPBYTE  pBuffer,
        DWORD   cbBuf,
  _Out_ LPDWORD pcbWritten
);

Parameter

[in] hPort

Vom Aufrufer bereitgestelltes Porthandle.

[in] pBuffer

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, der Daten enthält, die in den Port geschrieben werden sollen.

cbBuf

Vom Aufrufer bereitgestellte Größe von pBuffer in Byte.

[out] pcbWritten

Vom Aufrufer bereitgestellter Zeiger auf einen Speicherort, um die Anzahl von Bytes zu empfangen, die erfolgreich in den Port geschrieben wurden.

Rückgabewert

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte FALSE zurückgegeben werden.

Hinweise

Sprachmonitore und Portmonitorserver-DLLs sind erforderlich, um eine WritePort Funktion zu definieren und die Adresse der Funktion in eine MONITOR2-Struktur einzuschließen.

Das Handle, das als hPort-Argument der Funktion empfangen wird, ist das Porthandle, das von der OpenPort - oder OpenPortEx-Funktion des Monitors bereitgestellt wurde.

In der WritePort Regel fügt die Funktion eines Sprachmonitors sprachspezifische Befehle zum Datenstrom hinzu, der im Puffer enthalten ist, auf den pBuffer verweist, und übergibt dann den geänderten Datenstrom an die Funktion des Portmonitors WritePort .

Die Funktion einer Portmonitorserver-DLL ruft in der WritePort Regel WriteFile auf (in der Microsoft Windows SDK-Dokumentation beschrieben), um den Datenstrom an den Kernelmodus-Porttreiber zu senden.

Ein typischer Druckauftrag besteht aus mehreren Aufrufen von WritePort. Jeder Aufruf kann einen anderen cbBuf-Wert aufweisen.

Die Funktion sollte die Anzahl der erfolgreich geschriebenen Bytes zurückgeben, indem die Zahl an der Position platziert wird, auf die von pcbWritten verwiesen wird. Bei Sprachmonitoren darf diese Zahl nicht die Anzahl der zusätzlichen, sprachspezifischen Bytes enthalten, die dem Datenstrom hinzugefügt wurden.

Der Spooler bestimmt den Erfolg oder Fehler des Schreibvorgangs, indem er den Rückgabewert von überprüft WritePort, nicht die zurückgegebene Byteanzahl. Daher stellt eine zurückgegebene Byteanzahl von 0 (null) keinen fehlerhaften Schreibvorgang dar, es sei denn, die Funktion gibt FALSE zurück.

Eine Art systemseitig implementierter oder von monitor implementiertem Timeoutmechanismus muss sicherstellen, dass die WritePort Funktion innerhalb eines angemessenen Zeitraums zurückgegeben wird, um zu verhindern, dass der Spooler angehalten wird.

Es ist akzeptabel, dass ein Sprachmonitor die Routine eines Portmonitors außerhalb eines StartDocPort/EndDocPort-PaarsWritePort aufruft. Bei einigen Portmonitoren kann ein solcher Aufruf jedoch fehlschlagen, sodass der Sprachmonitor geschrieben werden muss, um diesen Fehler zu behandeln.