Fonction PeekNamedPipe (namedpipeapi.h)

Article
02/29/2024

Copie les données d’un canal nommé ou anonyme dans une mémoire tampon sans les supprimer du canal. Elle retourne également des informations sur les données dans le canal.

Syntaxe

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

Paramètres

[in] hNamedPipe

Une poignée au canal. Ce paramètre peut être un handle vers un canal nommé instance, comme retourné par la fonction CreateNamedPipe ou CreateFile, ou il peut s’agir d’un handle à l’extrémité de lecture d’un canal anonyme, comme retourné par la fonction CreatePipe. Le handle doit avoir GENERIC_READ accès au canal.

[out, optional] lpBuffer

Pointeur vers une mémoire tampon qui reçoit des données lues à partir du canal. Ce paramètre peut être NULL si aucune donnée ne doit être lue.

[in] nBufferSize

Taille de la mémoire tampon spécifiée par le paramètre lpBuffer , en octets. Ce paramètre est ignoré si lpBuffer a la valeur NULL.

[out, optional] lpBytesRead

Pointeur vers une variable qui reçoit le nombre d’octets lus à partir du canal. Ce paramètre peut être NULL si aucune donnée ne doit être lue.

[out, optional] lpTotalBytesAvail

Pointeur vers une variable qui reçoit le nombre total d’octets disponibles à lire à partir du canal. Ce paramètre peut être NULL si aucune donnée ne doit être lue.

[out, optional] lpBytesLeftThisMessage

Pointeur vers une variable qui reçoit le nombre d’octets restants dans ce message. Ce paramètre est égal à zéro pour les canaux nommés de type octet ou pour les canaux anonymes. Ce paramètre peut être NULL si aucune donnée ne doit être lue.

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

La fonction PeekNamedPipe est similaire à la fonction ReadFile avec les exceptions suivantes :

Les données sont lues dans le mode spécifié avec CreateNamedPipe. Par exemple, créer un canal avec PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Si vous modifiez le mode pour PIPE_READMODE_BYTE avec SetNamedPipeHandleState, ReadFile lira en mode octets, mais PeekNamedPipe continuera à lire en mode message.
Les données lues à partir du canal ne sont pas supprimées de la mémoire tampon du canal.
La fonction peut retourner des informations supplémentaires sur le contenu du canal.
La fonction retourne toujours immédiatement dans une application monothread, même s’il n’y a pas de données dans le canal. Le mode d’attente d’un handle de canal nommé (blocage ou non bloquant) n’a aucun effet sur la fonction.

Note La fonction PeekNamedPipe peut bloquer l’exécution des threads de la même façon qu’une fonction d’E/S lorsqu’elle est appelée sur un handle synchrone dans une application multithread. Pour éviter cette condition, utilisez un handle de canal créé pour les E/S asynchrones.

Si le handle spécifié est un handle de canal nommé en mode lecture d’octets, la fonction lit tous les octets disponibles jusqu’à la taille spécifiée dans nBufferSize. Pour un handle de canal nommé en mode lecture de message, la fonction lit le message suivant dans le canal. Si le message est supérieur à nBufferSize, la fonction retourne TRUE après avoir lu le nombre d’octets spécifié. Dans ce cas, lpBytesLeftThisMessage reçoit le nombre d’octets restants dans le message.

Windows 10, version 1709 : les canaux ne sont pris en charge que dans un conteneur d’application, c’est-à-dire, d’un processus UWP à un autre processus UWP qui fait partie de la même application. En outre, les canaux nommés doivent utiliser la syntaxe \\.\pipe\LOCAL\ du nom du canal.

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