共用方式為


PeekNamedPipe 函式 (namedpipeapi.h)

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

語法

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

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

[out, optional] lpBuffer

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

[in] nBufferSize

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

[out, optional] lpBytesRead

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

[out, optional] lpTotalBytesAvail

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

[out, optional] lpBytesLeftThisMessage

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

傳回值

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

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

備註

PeekNamedPipe 函式類似於 ReadFile 函式,但有下列例外狀況:

  • 數據會以 CreateNamedPipe 指定的模式讀取。 例如,使用 PIPE_TYPE_MESSAGE 建立管道 |PIPE_READMODE_MESSAGE。 如果您將模式變更為使用 SetNamedPipeHandleStatePIPE_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

另請參閱

CreateFile

CreateNamedPipe (CreateNamedPipe 函式)

CreatePipe

管道函式

管道概觀

ReadFile

WriteFile