預覽一個管道中的數據，或取得與管道中的數據有關的信息。
基本介紹
- 中文名：PeekNamedPipe
- 預覽一個：管道中的數據
- 會設定：GetLastError.
- Long：非零表示成功
- 零：失敗
返回值,VB聲明,參數表,注釋,VC++聲明,注釋,返回值,備註,
返回值
BooL，非零表示成功，零表示失敗。會設定GetLastError.
VB聲明
Declare Function PeekNamedPipe Lib "kernel32" Alias "PeekNamedPipe" (ByVal hNamedPipe As Long, lpBuffer As Any, ByVal nBufferSize As Long, lpBytesRead As Long, lpTotalBytesAvail As Long, lpBytesLeftThisMessage As Long) As Long
參數表
參數 | 類型及說明 |
hNamedPipe | Long，指定一個管道的句柄。這並不一定是某個命名管道的句柄——匿名管道同樣適用 |
lpBuffer | Any，指定要裝載數據的一個緩衝區的頭一個字元。可以為零（使用ByVal 0&） |
nBufferSize | Long，lpBuffer緩衝區長度 |
lpBytesRead | Long，保存裝載到緩衝區的字元數量 |
lpTotalBytesAvail | Long，保存管道中可用的字元數量 |
lpBytesLeftThisMessage | Long，保存這次讀操作後仍然保留在訊息中的字元數。只能為那些基於訊息的命名管道設定 |
注釋
由這個函式讀入的數據實際並不能從管道中刪除。如果要對一個管道進行輪詢，了解是否有可讀數據，那么使用這個函式特別理想.
VC++聲明
函式原型：
BOOL WINAPI PeekNamedPipe(
__in HANDLE hNamedPipe, //管道句柄
__out_opt LPVOID lpBuffer, //讀取輸出緩衝區，可選
__in DWORD nBufferSize, //緩衝區大小
__out_opt LPDWORD lpBytesRead, //接收從管道中讀取數據的變數的指針，可選
__out_opt LPDWORD lpTotalBytesAvail, //接收從管道讀取的位元組總數
__out_opt LPDWORD lpBytesLeftThisMessage
);
注釋
參數
hNamedPipe [in]
管道句柄。這個參數可以是一個命名管道實例句柄，返回，由CreateNamedPipe或CreateFile函式，或者它可以是一個匿名管道的讀端句柄，返回由CREATEPIPE功能。句柄必須有GENERIC_READ許可權的管道。
lpBuffer [out, optional]
接收從管道讀取數據的緩衝區的指針。如果沒有數據要讀取，此參數可以為NULL。
nBufferSize [in]
lpBuffer參數以位元組為單位，由指定的緩衝區大小。如果lpBuffer是NULL，則忽略此參數。
lpBytesRead [out, optional]
接收從管道中讀取的位元組數的變數的指針。此參數可以為NULL，如果沒有數據要讀取。
lpTotalBytesAvail [out, optional]
一個指針變數，接收從管道讀取的位元組總數。此參數可以為NULL，如果沒有數據要讀取。
lpBytesLeftThisMessage [out, optional]
指向剩餘的位元組數的變數的指針訊息。此參數將是零位元組類型的命名管道或匿名管道。此參數可以為NULL，如果沒有數據要讀取。
返回值
如果函式成功，返回值為非零。
如果函式失敗，返回值是零。為了獲得更多錯誤信息，調用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將收到的訊息中剩餘的位元組數。
