ReadPort-Funktion (winsplp.h)

Artikel
02/27/2024

Die Funktion eines ReadPort Portmonitors liest Daten von einem Druckeranschluss.

Syntax

BOOL ReadPort(
  _In_  HANDLE  hPort,
  _Out_ LPBYTE  pBuffer,
        DWORD   cbBuffer,
  _Out_ LPDWORD pcbRead
);

Parameter

[in] hPort

Vom Aufrufer bereitgestelltes Porthandle.

[out] pBuffer

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, um vom Port gelesene Daten zu empfangen.

cbBuffer

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

[out] pcbRead

Vom Aufrufer bereitgestellter Zeiger auf einen Speicherort, um die Anzahl der erfolgreich vom Port gelesenen Bytes zu empfangen.

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 ReadPort 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 Regel ruft die Funktion eines Sprachmonitors ReadPort die Funktion des zugeordneten Portmonitors ReadPort auf und gibt den abgerufenen Pufferinhalt an den Aufrufer zurück.

Darüber hinaus kann ein Sprachmonitor einen separaten Thread erstellen, der die Funktion des Portmonitors ReadPort aufruft, um nach unerwünschten status Informationen zu suchen. Wenn ein solcher Lesevorgang erfolgreich ist, sollten die status Informationen an den Spooler zurückgegeben werden, indem SetPort aufgerufen wird (siehe Microsoft Windows SDK Dokumentation).

In der Regel ruft die Funktion einer Portmonitorserver-DLL ReadPortReadFile auf (in der Windows SDK-Dokumentation beschrieben), um Daten vom Kernelmodus-Porttreiber abzurufen. Die Funktion gibt nur die Daten an den Aufrufer zurück.

Obwohl sowohl Sprachmonitore als auch Portmonitore Funktionen definieren ReadPort und ihre Adressen in MONITOR2 Strukturen platzieren müssen, wird die Funktion eines Sprachmonitors ReadPort nie tatsächlich vom Spooler oder einer Anwendung aufgerufen. Die Funktion ist ausschließlich für die interne Verwendung des Sprachmonitors selbst vorgesehen.

Beispielsweise pjlmon.dll erstellt der Beispielsprachmonitor einen separaten Thread, der einen eigenen ReadPort thread aufruft, um watch für nicht angeforderte Druckerinformationen status, und die ReadPort Funktion ruft die Funktion des Portmonitors ReadPort auf. Wenn der Portmonitor Daten an den Sprachmonitor zurückgibt, analysiert der Sprachmonitor die empfangenen Daten und ruft SetPort auf (in der Windows SDK-Dokumentation beschrieben), um status Informationen an den Spooler zu senden.

Die Funktion sollte die Anzahl der bytes zurückgeben, die erfolgreich gelesen wurden, indem die Zahl an der Position platziert wird, auf die von pcbRead verwiesen wird. Der Aufrufer bestimmt den Erfolg oder Fehler des Schreibvorgangs, indem er den Rückgabewert überprüft ReadPort's , nicht die zurückgegebene Byteanzahl. Daher stellt eine zurückgegebene Byteanzahl von 0 (null) keinen Fehler beim Lesen dar, es sei denn, die Funktion gibt FALSE zurück.

Eine Art systemseitig implementierter oder von monitor implementiertem Timeoutmechanismus muss sicherstellen, dass die ReadPort 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-PaarsReadPort aufruft. (Ein solcher Aufruf kann von einem Thread generiert werden, der nach unerwünschten status sucht.) Bei einigen Portmonitoren kann ein solcher Aufruf jedoch fehlschlagen, sodass der Sprachmonitor geschrieben werden muss, um diesen Fehler zu behandeln.