Funzione PeekNamedPipe (namedpipeapi.h)

Articolo
02/29/2024

Copia i dati da una pipe denominata o anonima in un buffer senza rimuoverli dalla pipe. Restituisce anche informazioni sui dati nella pipe.

Sintassi

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

Parametri

[in] hNamedPipe

Handle per la pipe. Questo parametro può essere un handle per un'istanza di named pipe, come restituito dalla funzione CreateNamedPipe o CreateFile oppure può essere un handle alla fine di lettura di una pipe anonima, come restituito dalla funzione CreatePipe . L'handle deve avere GENERIC_READ l'accesso alla pipe.

[out, optional] lpBuffer

Puntatore a un buffer che riceve i dati letti dalla pipe. Questo parametro può essere NULL se non è necessario leggere alcun dato.

[in] nBufferSize

Dimensioni del buffer specificato dal parametro lpBuffer , in byte. Questo parametro viene ignorato se lpBuffer è NULL.

[out, optional] lpBytesRead

Puntatore a una variabile che riceve il numero di byte letti dalla pipe. Questo parametro può essere NULL se non è necessario leggere alcun dato.

[out, optional] lpTotalBytesAvail

Puntatore a una variabile che riceve il numero totale di byte disponibili per la lettura dalla pipe. Questo parametro può essere NULL se non è necessario leggere alcun dato.

[out, optional] lpBytesLeftThisMessage

Puntatore a una variabile che riceve il numero di byte rimanenti nel messaggio. Questo parametro sarà zero per le named pipe di tipo byte o per le pipe anonime. Questo parametro può essere NULL se non è necessario leggere alcun dato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione PeekNamedPipe è simile alla funzione ReadFile con le eccezioni seguenti:

I dati vengono letti nella modalità specificata con CreateNamedPipe. Ad esempio, creare una pipe con PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Se si imposta la modalità su PIPE_READMODE_BYTE con SetNamedPipeHandleState, ReadFile leggerà in modalità byte, ma PeekNamedPipe continuerà a essere letto in modalità messaggio.
I dati letti dalla pipe non vengono rimossi dal buffer della pipe.
La funzione può restituire informazioni aggiuntive sul contenuto della pipe.
La funzione restituisce sempre immediatamente in un'applicazione a thread singolo, anche se non sono presenti dati nella pipe. La modalità di attesa di un handle named pipe (blocco o nonblocking) non ha alcun effetto sulla funzione.

Nota La funzione PeekNamedPipe può bloccare l'esecuzione del thread allo stesso modo in cui qualsiasi funzione di I/O può essere chiamata su un handle sincrono in un'applicazione multithread. Per evitare questa condizione, usare un handle pipe creato per le operazioni di I/O asincrone.

Se l'handle specificato è un handle named pipe in modalità di lettura byte, la funzione legge tutti i byte disponibili fino alle dimensioni specificate in nBufferSize. Per un handle named pipe in modalità di lettura messaggio, la funzione legge il messaggio successivo nella pipe. Se il messaggio è maggiore di nBufferSize, la funzione restituisce TRUE dopo la lettura del numero specificato di byte. In questo caso , lpBytesLeftThisMessage riceverà il numero di byte rimanenti nel messaggio.

Windows 10 versione 1709: le pipe sono supportate solo all'interno di un contenitore di app, ad esempio da un processo UWP a un altro processo UWP che fa parte della stessa app. Inoltre, named pipe deve usare la sintassi \\.\pipe\LOCAL\ per il nome della pipe.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	namedpipeapi.h
Libreria	Kernel32.lib
DLL	Kernel32.dll