TransactNamedPipe 関数 (namedpipeapi.h)

メッセージを書き込む関数と、指定した名前付きパイプからメッセージを読み取る関数を 1 つの操作に結合します。

構文

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 構造体へのポインター。 hNamedPipe が FILE_FLAG_OVERLAPPED で開かれた場合は、この構造体が必要です。

hNamedPipe が FILE_FLAG_OVERLAPPED で開かれた場合、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 は操作が完了するまで戻りません。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

読み取るメッセージが nOutBufferSize パラメーターで指定されたバッファーより長い場合、 TransactNamedPipe は FALSE を 返し、 GetLastError 関数はERROR_MORE_DATAを返します。 メッセージの残りの部分は、ReadFile、ReadFileEx、または PeekNamedPipe の後続の呼び出しで読み取ることができます。

注釈

サーバーがメッセージ型パイプとしてパイプを作成しなかった場合、またはパイプ ハンドルがメッセージ読み取りモードでない場合、TransactNamedPipe は失敗します。 たとえば、クライアントがサーバーと同じコンピューターで実行されていて、\.\pipe\pipename 形式を使用してパイプを開くと、パイプは名前付きパイプ ファイル システム (NPFS) によってバイト モードで開かれます。 クライアントが \\server\pipe\pipename という形式を使用している場合、リダイレクターはメッセージ モードでパイプを開きます。 バイト モードのパイプ ハンドルは、 SetNamedPipeHandleState 関数を使用してメッセージ読み取りモードに変更できます。

lpOutBuffer パラメーターで指定されたバッファーにデータが書き込まれるまで、関数を正常に完了できません。 lpOverlapped パラメーターを使用すると、操作がバックグラウンドで実行されている間に、呼び出し元のスレッドが他のタスクを実行できるようになります。

名前付きパイプ トランザクションの最大保証サイズは 64 キロバイトです。 場合によっては、トランザクションに参加している OS のバージョンや動的ネットワークの状態によっては、64 キロバイトを超えるトランザクションが可能です。 ただし、64 キロバイトを超えるトランザクションが成功するという保証はありません。 そのため、名前付きパイプ トランザクションは 64 キロバイトのデータに制限することをお勧めします。

Windows 10バージョン 1709: パイプは、アプリ コンテナー内でのみサポートされます。つまり、1 つの UWP プロセスから、同じアプリの一部である別の UWP プロセスまでです。 また、名前付きパイプでは、パイプ名の構文 \\.\pipe\LOCAL\ を使用する必要があります。

例

例については、「 名前付きパイプのトランザクション」を参照してください。

要件

関連項目

CreateEvent

CreateFile

CreateNamedPipe

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED

PeekNamedPipe

パイプ関数

パイプの概要

ReadFile

ReadFileEx

SetNamedPipeHandleState