PeekNamedPipe 函式 (namedpipeapi.h)

發行項
03/05/2024

將數據從具名或匿名管道複製到緩衝區，而不需從管道中移除。它也會傳回管道中數據的相關信息。

語法

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

參數

[in] hNamedPipe

管道的句柄。此參數可以是命名管道實例的句柄，如 CreateNamedPipe 或 CreateFile 函式所傳回，也可以是匿名管道讀取端的句柄，如 CreatePipe 函式所傳回。句柄必須GENERIC_READ管道的存取權。

[out, optional] lpBuffer

緩衝區的指標，接收從管道讀取的數據。如果沒有讀取任何數據，此參數可以是 NULL 。

[in] nBufferSize

lpBuffer 參數所指定的緩衝區大小，以位元組為單位。如果 lpBuffer 為 NULL，則會忽略此參數。

[out, optional] lpBytesRead

從管道讀取位元組數目的變數指標。如果沒有讀取任何數據，此參數可以是 NULL 。

[out, optional] lpTotalBytesAvail

變數的指標，接收可從管道讀取的位元組總數。如果沒有讀取任何數據，此參數可以是 NULL 。

[out, optional] lpBytesLeftThisMessage

接收此訊息中剩餘位元元組數目之變數的指標。這個參數會是位元組類型命名管道或匿名管道的零。如果沒有讀取任何數據，此參數可以是 NULL 。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

PeekNamedPipe 函式類似於 ReadFile 函式，但有下列例外狀況：

數據會以 CreateNamedPipe 指定的模式讀取。例如，使用 PIPE_TYPE_MESSAGE 建立管道 |PIPE_READMODE_MESSAGE。如果您將模式變更為使用 SetNamedPipeHandleState PIPE_READMODE_BYTE，ReadFile 會以位元組模式讀取，但 PeekNamedPipe 會繼續在訊息模式中讀取。
從管道讀取的數據不會從管道的緩衝區中移除。
函式可以傳回管道內容的其他資訊。
函式一律會在單一線程應用程式中立即傳回，即使管道中沒有數據也一樣。具名管道句柄的等候模式 (封鎖或非封鎖) 不會影響函式。

注意PeekNamedPipe 函式可以在多線程應用程式中在同步句柄上呼叫時，以相同方式封鎖線程執行。若要避免這種情況，請使用針對異步 I/O 建立的管道句柄。

如果指定的句柄是位元組讀取模式中的具名管道句柄，函式會讀取所有可用的位元組，最多可讀取 nBufferSize 中指定的大小。針對訊息讀取模式中的具名管道句柄，函式會在管道中讀取下一個訊息。如果訊息大於 nBufferSize，則函式會在讀取指定的位元元數目之後傳回 TRUE 。在此情況下， lpBytesLeftThisMessage 將會收到訊息中剩餘的位元組數目。

Windows 10 版本 1709：管道僅在應用程式容器內受到支援;亦即，從一個 UWP 進程到另一個屬於相同應用程式的 UWP 進程。此外，命名管道必須使用管道名稱的語法 \\.\pipe\LOCAL\ 。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	namedpipeapi.h
程式庫	Kernel32.lib
DLL	Kernel32.dll