TransactNamedPipe 函数 (namedpipeapi.h)

项目
03/05/2024

将向指定命名管道写入消息并从中读取消息的函数合并到单个操作中。

语法

BOOL TransactNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in]                LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out]               LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out]               LPDWORD      lpBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

参数

[in] hNamedPipe

CreateNamedPipe 或 CreateFile 函数返回的命名管道的句柄。

此参数也可以是匿名管道的句柄，由 CreatePipe 函数返回。

[in] lpInBuffer

指向缓冲区的指针，其中包含要写入管道的数据。

[in] nInBufferSize

输入缓冲区的大小（以字节为单位）。

[out] lpOutBuffer

指向接收从管道读取的数据的缓冲区的指针。

[in] nOutBufferSize

输出缓冲区的大小（以字节为单位）。

[out] lpBytesRead

指向变量的指针，该变量接收从管道读取的字节数。

如果 lpOverlapped 为 NULL， 则 lpBytesRead 不能为 NULL。

如果 lpOverlapped 不为 NULL， 则 lpBytesRead 可以为 NULL。如果这是一个重叠的读取操作，可以通过调用 GetOverlappedResult 来获取读取的字节数。如果 hNamedPipe 与 I/O 完成端口相关联，可以通过调用 GetQueuedCompletionStatus 获取读取的字节数。

[in, out, optional] lpOverlapped

指向 OVERLAPPED 结构的指针。如果使用 FILE_FLAG_OVERLAPPED 打开 hNamedPipe ，则需要此结构。

如果使用 FILE_FLAG_OVERLAPPED 打开 hNamedPipe ， 则 lpOverlapped 参数不得为 NULL。它必须指向有效的 OVERLAPPED 结构。如果 hNamedPipe 是使用 FILE_FLAG_OVERLAPPED 创建的，并且 lpOverlapped 为 NULL，则该函数可能会错误地报告操作已完成。

如果 hNamedPipe 是使用 FILE_FLAG_OVERLAPPED 打开的，并且 lpOverlapped 不是 NULL， 则 TransactNamedPipe 将作为重叠操作执行。 OVERLAPPED 结构应包含手动重置事件对象 (可以使用 CreateEvent 函数) 创建。如果操作无法立即完成，TransactNamedPipe 将返回 FALSE，GetLastError 返回ERROR_IO_PENDING。在这种情况下，事件对象在 TransactNamedPipe 返回之前设置为非对齐状态，并在事务完成时将其设置为信号状态。此外，可以使用 GetQueuedCompletionStatus 或 GetQueuedCompletionStatusEx 函数在重叠操作完成时收到通知。在这种情况下，无需在 OVERLAPPED 结构中分配手动重置事件，并且针对 hNamedPipe 执行的完成方式与异步读取或写入操作相同。有关重叠操作的详细信息，请参阅管道。

如果 hNamedPipe 未使用 FILE_FLAG_OVERLAPPED 打开， 则 TransactNamedPipe 在操作完成之前不会返回。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

如果要读取的消息长于 nOutBufferSize 参数指定的缓冲区，TransactNamedPipe 将返回 FALSE，GetLastError 函数返回ERROR_MORE_DATA。消息的其余部分可以通过后续调用 ReadFile、 ReadFileEx 或 PeekNamedPipe 进行读取。

注解

如果服务器未将管道创建为消息类型管道，或者管道句柄未处于消息读取模式，TransactNamedPipe 将失败。例如，如果客户端与服务器在同一台计算机上运行，并使用 \.\pipe\pipename 格式打开管道，则命名管道文件系统 (NPFS) 以字节模式打开管道。如果客户端使用格式 \\server\pipe\pipename，则重定向程序将在消息模式下打开管道。可以使用 SetNamedPipeHandleState 函数将字节模式管道句柄更改为消息读取模式。

在将数据写入 lpOutBuffer 参数指定的缓冲区之前，函数无法成功完成。 lpOverlapped 参数可用于使调用线程能够在后台执行操作时执行其他任务。

命名管道事务的最大保证大小为 64 KB。在某些有限情况下，可能会发生超过 64 KB 的事务，具体取决于参与事务的 OS 版本和动态网络条件。但是，无法保证超过 64 KB 的事务会成功。因此，建议将命名管道事务限制为 64 KB 的数据。

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

示例

有关示例，请参阅命名管道上的事务。

要求

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