Funzione SetNamedPipeHandleState (namedpipeapi.h)

Articolo
08/25/2023

Imposta la modalità di lettura e la modalità di blocco della named pipe specificata. Se l'handle specificato è alla fine del client di una named pipe e se il processo del server named pipe si trova in un computer remoto, la funzione può essere usata anche per controllare il buffer locale.

Sintassi

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Parametri

[in] hNamedPipe

Handle per l'istanza della named pipe. Questo parametro può essere un handle alla fine del server della pipe, come restituito dalla funzione CreateNamedPipe o alla fine client della pipe, come restituito dalla funzione CreateFile . L'handle deve avere GENERIC_WRITE accesso alla named pipe per una pipe di sola scrittura o di sola lettura o scrittura oppure deve avere GENERIC_READ e FILE_WRITE_ATTRIBUTES l'accesso per una pipe di sola lettura.

Questo parametro può anche essere un handle per una pipe anonima, come restituito dalla funzione CreatePipe .

[in, optional] lpMode

Nuova modalità pipe. La modalità è una combinazione di un flag in modalità lettura e di un flag in modalità di attesa. Questo parametro può essere NULL se la modalità non è impostata. Specificare una delle modalità seguenti.

Mode	Significato
PIPE_READMODE_BYTE 0x00000000	I dati sono letti dalla pipe come flusso di byte. Questa modalità è l'impostazione predefinita se non viene specificato alcun flag in modalità di lettura.
PIPE_READMODE_MESSAGE 0x00000002	I dati vengono letti dalla pipe come flusso di messaggi. La funzione ha esito negativo se questo flag viene specificato per una pipe di tipo byte.

È possibile specificare una delle modalità di attesa seguenti.

Mode	Significato
PIPE_WAIT 0x00000000	La modalità di blocco è abilitata. Questa modalità è l'impostazione predefinita se non è specificato alcun flag in modalità di attesa. Quando viene specificato un handle pipe in modalità di blocco nella funzione ReadFile, WriteFile o ConnectNamedPipe , le operazioni non vengono completate fino a quando non sono presenti dati da leggere, tutti i dati vengono scritti o un client è connesso. L'uso di questa modalità può comportare un'attesa illimitata in alcune situazioni per consentire a un processo client di eseguire un'azione.
PIPE_NOWAIT 0x00000001	La modalità non bloccante è abilitata. In questa modalità ReadFile, WriteFile e ConnectNamedPipe restituiscono sempre immediatamente. Si noti che la modalità di non blocco è supportata per la compatibilità con Microsoft LAN Manager versione 2.0 e non deve essere usata per ottenere input e output asincroni (I/O) con named pipe.

Mode

Significato

PIPE_WAIT
0x00000000

La modalità di blocco è abilitata. Questa modalità è l'impostazione predefinita se non è specificato alcun flag in modalità di attesa. Quando viene specificato un handle pipe in modalità di blocco nella funzione ReadFile, WriteFile o ConnectNamedPipe , le operazioni non vengono completate fino a quando non sono presenti dati da leggere, tutti i dati vengono scritti o un client è connesso. L'uso di questa modalità può comportare un'attesa illimitata in alcune situazioni per consentire a un processo client di eseguire un'azione.

PIPE_NOWAIT
0x00000001

La modalità non bloccante è abilitata. In questa modalità ReadFile, WriteFile e ConnectNamedPipe restituiscono sempre immediatamente. Si noti che la modalità di non blocco è supportata per la compatibilità con Microsoft LAN Manager versione 2.0 e non deve essere usata per ottenere input e output asincroni (I/O) con named pipe.

[in, optional] lpMaxCollectionCount

Numero massimo di byte raccolti nel computer client prima della trasmissione al server. Questo parametro deve essere NULL se l'handle pipe specificato è alla fine del server di una named pipe o se i processi client e server si trovano nello stesso computer. Questo parametro viene ignorato se il processo client specifica il flag FILE_FLAG_WRITE_THROUGH nella funzione CreateFile al momento della creazione dell'handle. Questo parametro può essere NULL se il numero di raccolte non è impostato.

[in, optional] lpCollectDataTimeout

Tempo massimo, in millisecondi, che può passare prima che una named pipe remota trasferisca le informazioni sulla rete. Questo parametro deve essere NULL se l'handle pipe specificato è alla fine del server di una named pipe o se i processi client e server si trovano nello stesso computer. Questo parametro viene ignorato se il processo client ha specificato il flag FILE_FLAG_WRITE_THROUGH nella funzione CreateFile al momento della creazione dell'handle. Questo parametro può essere NULL se il numero di raccolte non è impostato.

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

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.

Esempio

Per un esempio, vedere Named Pipe Client.For an example, see Named Pipe Client.

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