transactNamedPipe 函式 (namedpipeapi.h)

發行項
03/13/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

重疊結構的指標。如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 開啟，則需要此結構。

如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 開啟， 則 lpOverlapped 參數不得為 NULL。它必須指向有效的重疊結構。如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 建立，而 lpOverlapped 為 NULL，則函式可能會錯誤地報告作業已完成。

如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 開啟，且 lpOverlapped 不是 NULL，TransactNamedPipe 會以重疊的作業執行。 OVERLAPPED 結構應該包含手動重設事件物件 (，您可以使用 CreateEvent 函式) 來建立此物件。如果作業無法立即完成， TransactNamedPipe 會傳回 FALSE ，而 GetLastError 會傳回ERROR_IO_PENDING。在此情況下，事件物件會在 TransactNamedPipe 傳回之前設定為非ignaled 狀態，並在交易完成時設定為已發出訊號的狀態。此外，您可以使用 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。在某些情況下，視參與交易和動態網路狀況的 OS 版本而定，可能會有超過 64 KB 的交易。不過，不保證超過 64 KB 的交易將會成功。因此，建議命名管道交易限制為 64 KB 的數據。

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

範例

如需範例，請參閱命名管道上的交易。

規格需求

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