ReadPort 函式 (winsplp.h)

發行項
03/01/2024

埠監視器的函 ReadPort 式會從印表機埠讀取數據。

語法

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

參數

[in] hPort

呼叫端提供的埠句柄。

[out] pBuffer

呼叫端提供的緩衝區指標，以接收從埠讀取的數據。

cbBuffer

pBuffer 的呼叫端提供大小，以位元組為單位。

[out] pcbRead

呼叫端提供的位置指標，以接收從埠成功讀取的位元元組數目。

傳回值

如果作業成功，函式應該會傳回 TRUE。否則應該會傳回 FALSE。

備註

需要語言監視器和埠監視伺服器 DLL，才能定義函 ReadPort 式，並在 MONITOR2 結構中包含函式的位址。

接收為函式 hPort 自變數的句柄是監視器的 OpenPort 或 OpenPortEx 函式所提供的埠句柄。

一般而言，語言監視器的 ReadPort 函式會呼叫相關聯的埠監視器函 ReadPort 式，並將取得的緩衝區內容傳回給呼叫端。

此外，語言監視器可能會建立個別的線程，以呼叫埠監視器的 ReadPort 函式來檢查未要求的狀態資訊。如果這類讀取作業成功，應該呼叫 Microsoft Windows SDK 檔中所述的 SetPort (，將狀態資訊傳回至多任務緩衝處理程式) 。

一般而言，埠監視伺服器 DLL 的ReadPort函式會呼叫 ReadFile (，如 Windows SDK 檔所述，) 從內核模式埠驅動程式取得數據。函式只會將數據傳回給呼叫端。

即使語言監視器和埠監視器都必須定義 ReadPort 函式，並將其位址放在MONITOR2結構中，語言監視器的 ReadPort 函式永遠不會由多任務緩衝處理程式或應用程式實際呼叫。函式僅適用於語言監視器本身的內部使用。

例如，pjlmon.dll 範例語言監視器會建立個別線程，以呼叫自己的ReadPort線程來 watch，以取得未經請求的印表機狀態資訊，而函ReadPort式會呼叫埠監視器的 ReadPort 函式。當埠監視器將數據傳回語言監視器時，語言監視器會剖析收到的數據，並呼叫 Windows SDK 檔中所述的 SetPort (，) 將狀態資訊傳送至多任務緩衝處理程式。

此函式應該傳回成功讀取的位元組數目，方法是將數位放在 由 HTTPRead 指向的位置。呼叫端會檢查 ReadPort's 傳回值，而不是傳回的位元組計數，來判斷寫入作業的成功或失敗。因此，除非函式傳回 FALSE，否則傳回的位元組計數不代表失敗的讀取。

某種系統實作或監視實作的逾時機制必須確保函 ReadPort 式會在合理的時間內傳回，以避免停止多任務緩衝處理程式。

語言監視器在 StartDocPort EndDocPort/ 配對之外呼叫埠監視器ReadPort的例程是可接受的。 (這類呼叫可能是由線程檢查未要求的狀態所產生。) 不過，某些埠監視器可能會失敗這類呼叫，因此必須寫入語言監視器來處理此失敗。