peekNamedPipe 函数 (namedpipeapi.h)

项目
03/08/2023

将数据从命名管道或匿名管道复制到缓冲区中，而不将其从管道中删除。它还返回有关管道中的数据的信息。

语法

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 函数时一样。若要避免这种情况，请使用为异步 I/O 创建的管道句柄。

如果指定的句柄是字节读取模式下的命名管道句柄，则函数读取所有可用字节，最大大小为 nBufferSize 中指定的大小。对于消息读取模式下的命名管道句柄，函数读取管道中的下一条消息。如果消息大于 nBufferSize，则函数在读取指定的字节数后返回 TRUE 。在这种情况下， lpBytesLeftThisMessage 将接收消息中剩余的字节数。

Windows 10版本 1709：管道仅在应用容器中受支持;即，从一个 UWP 进程到另一个属于同一应用的 UWP 进程。此外，命名管道必须使用语法 \\.\pipe\LOCAL\ 来表示管道名称。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows 2000 Server [桌面应用 \|UWP 应用]
目标平台	Windows
标头	namedpipeapi.h
Library	Kernel32.lib
DLL	Kernel32.dll