PeekNamedPipe 関数 (namedpipeapi.h)

  • [アーティクル]

名前付きパイプまたは匿名パイプからデータをパイプから削除せずにバッファーにコピーします。 また、パイプ内のデータに関する情報も返します。

構文

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

このメッセージに残っているバイト数を受け取る変数へのポインター。 このパラメーターは、バイト型の名前付きパイプの場合は 0、匿名パイプの場合は 0 になります。 データを読み取る必要がない場合、このパラメーターは NULL にすることができます。

戻り値

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

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、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: パイプは、アプリ コンテナー内でのみサポートされます。つまり、1 つの UWP プロセスから、同じアプリの一部である別の UWP プロセスまでです。 また、名前付きパイプでは、パイプ名の構文 \\.\pipe\LOCAL\ を使用する必要があります。

要件

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

関連項目

CreateFile

CreateNamedPipe

CreatePipe

パイプ関数

パイプの概要

ReadFile

WriteFile