CreatePipe, fonction (namedpipeapi.h)

Article
03/04/2024

Crée un canal anonyme et retourne des handles aux extrémités de lecture et d’écriture du canal.

Syntaxe

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

Paramètres

[out] hReadPipe

Pointeur vers une variable qui reçoit le handle de lecture pour le canal.

[out] hWritePipe

Pointeur vers une variable qui reçoit le handle d’écriture pour le canal.

[in, optional] lpPipeAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES qui détermine si le handle retourné peut être hérité par les processus enfants. Si lpPipeAttributes a la valeur NULL, le handle ne peut pas être hérité.

Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour le nouveau canal. Si lpPipeAttributes a la valeur NULL, le canal obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut d’un canal proviennent du jeton principal ou d’emprunt d’identité du créateur.

[in] nSize

Taille de la mémoire tampon pour le canal, en octets. La taille n’est qu’une suggestion ; le système utilise la valeur pour calculer un mécanisme de mise en mémoire tampon approprié. Si ce paramètre est égal à zéro, le système utilise la taille de mémoire tampon par défaut.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

CreatePipe crée le canal, en affectant la taille de canal spécifiée à la mémoire tampon de stockage. CreatePipe crée également des handles que le processus utilise pour lire et écrire dans la mémoire tampon dans les appels suivants aux fonctions ReadFile et WriteFile .

Pour lire à partir du canal, un processus utilise le handle de lecture dans un appel à la fonction ReadFile . ReadFile retourne lorsque l’une des conditions suivantes est remplie : une opération d’écriture se termine à l’extrémité du canal d’écriture, le nombre d’octets demandés a été lu ou une erreur se produit.

Lorsqu’un processus utilise WriteFile pour écrire dans un canal anonyme, l’opération d’écriture n’est pas terminée tant que tous les octets n’ont pas été écrits. Si la mémoire tampon du canal est pleine avant que tous les octets soient écrits, WriteFile ne retourne pas de mémoire tampon tant qu’un autre processus ou thread n’utilise pas ReadFile pour rendre plus d’espace de mémoire tampon disponible.

Les canaux anonymes sont implémentés à l’aide d’un canal nommé avec un nom unique. Par conséquent, vous pouvez souvent passer un handle à un canal anonyme à une fonction qui nécessite un handle à un canal nommé.

Si CreatePipe échoue, le contenu des paramètres de sortie est indéterminé. Dans ce cas, aucune hypothèse ne doit être faite concernant leur contenu.

Pour libérer les ressources utilisées par un canal, l’application doit toujours fermer les handles lorsqu’ils ne sont plus nécessaires, ce qui est possible en appelant la fonction CloseHandle ou lorsque le processus associé aux handles instance se termine. Notez qu’un instance d’un canal peut avoir plusieurs handles associés. Une instance d’un canal est toujours supprimée lorsque le dernier handle du instance du canal nommé est fermé.

Exemples

Pour obtenir un exemple, consultez Création d’un processus enfant avec une entrée et une sortie redirigées.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	namedpipeapi.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll