TransactNamedPipe 関数 (namedpipeapi.h)

[アーティクル]
03/08/2023

メッセージを書き込む関数と、指定した名前付きパイプからメッセージを読み取る関数を 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\ を使用する必要があります。

例

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

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	namedpipeapi.h
Library	Kernel32.lib
[DLL]	Kernel32.dll

TransactNamedPipe 関数 (namedpipeapi.h)

構文

パラメーター

戻り値

注釈

例

要件

関連項目

フィードバック

フィードバック

その他のリソース