Funzione CreatePipe (namedpipeapi.h)

Articolo
02/29/2024

Crea una pipe anonima e restituisce handle alle estremità di lettura e scrittura della pipe.

Sintassi

BOOL CreatePipe(
  [out]          PHANDLE               hReadPipe,
  [out]          PHANDLE               hWritePipe,
  [in, optional] LPSECURITY_ATTRIBUTES lpPipeAttributes,
  [in]           DWORD                 nSize
);

Parametri

[out] hReadPipe

Puntatore a una variabile che riceve l'handle di lettura per la pipe.

[out] hWritePipe

Puntatore a una variabile che riceve l'handle di scrittura per la pipe.

[in, optional] lpPipeAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES che determina se l'handle restituito può essere ereditato dai processi figlio. Se lpPipeAttributes è NULL, l'handle non può essere ereditato.

Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per la nuova pipe. Se lpPipeAttributes è NULL, la pipe ottiene un descrittore di sicurezza predefinito. Gli ACL nel descrittore di sicurezza predefinito per una pipe provengono dal token primario o di rappresentazione del creatore.

[in] nSize

Dimensioni del buffer per la pipe, in byte. La dimensione è solo un suggerimento; il sistema usa il valore per calcolare un meccanismo di buffering appropriato. Se questo parametro è zero, il sistema usa le dimensioni predefinite del buffer.

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

CreatePipe crea la pipe, assegnando le dimensioni della pipe specificate al buffer di archiviazione. CreatePipe crea anche handle usati dal processo per leggere e scrivere nel buffer nelle chiamate successive alle funzioni ReadFile e WriteFile .

Per leggere dalla pipe, un processo usa l'handle di lettura in una chiamata alla funzione ReadFile . ReadFile restituisce quando è true una delle operazioni di scrittura seguenti: un'operazione di scrittura viene completata alla fine della scrittura della pipe, il numero di byte richiesti è stata letta o si verifica un errore.

Quando un processo usa WriteFile per scrivere in una pipe anonima, l'operazione di scrittura non viene completata fino a quando non vengono scritti tutti i byte. Se il buffer della pipe è pieno prima della scrittura di tutti i byte, WriteFile non restituisce fino a quando un altro processo o thread usa ReadFile per rendere disponibile più spazio buffer.

Le pipe anonime vengono implementate usando una named pipe con un nome univoco. Di conseguenza, spesso è possibile passare un handle a una pipe anonima a una funzione che richiede un handle a una named pipe.

Se CreatePipe ha esito negativo, il contenuto dei parametri di output è indeterminato. In questo evento non devono essere prese ipotesi sul loro contenuto.

Per liberare le risorse usate da una pipe, l'applicazione deve sempre chiudere handle quando non sono più necessari, operazione eseguita chiamando la funzione CloseHandle o quando termina il processo associato agli handle di istanza. Si noti che a un'istanza di una pipe possono essere associati più handle. Un'istanza di una pipe viene sempre eliminata quando l'ultimo handle all'istanza della named pipe viene chiuso.

Esempio

Per un esempio, vedere Creazione di un processo figlio con input e output reindirizzati.

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