GetNamedPipeHandleStateA, fonction (winbase.h)

Article
03/08/2023

Récupère des informations sur un canal nommé spécifié. Les informations retournées peuvent varier pendant la durée de vie d’un instance du canal nommé.

Syntaxe

BOOL GetNamedPipeHandleStateA(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPDWORD lpState,
  [out, optional] LPDWORD lpCurInstances,
  [out, optional] LPDWORD lpMaxCollectionCount,
  [out, optional] LPDWORD lpCollectDataTimeout,
  [out, optional] LPSTR   lpUserName,
  [in]            DWORD   nMaxUserNameSize
);

Paramètres

[in] hNamedPipe

Handle vers le canal nommé pour lequel les informations sont souhaitées. Le handle doit avoir un accès GENERIC_READ pour un canal en lecture seule ou en lecture/écriture, ou il doit avoir un accès GENERIC_WRITE et FILE_READ_ATTRIBUTES pour un canal d’écriture seule.

Ce paramètre peut également être un handle vers un canal anonyme, tel que retourné par la fonction CreatePipe .

[out, optional] lpState

Pointeur vers une variable qui indique l’état actuel du handle. Ce paramètre peut être NULL si ces informations ne sont pas nécessaires. Vous pouvez spécifier l’une ou l’autre des valeurs suivantes.

Valeur	Signification
PIPE_NOWAIT 0x00000001	Le handle de canal est en mode non bloquant. Si cet indicateur n’est pas spécifié, le handle de canal est en mode bloquant.
PIPE_READMODE_MESSAGE 0x00000002	Le handle de canal est en mode lecture de message. Si cet indicateur n’est pas spécifié, le handle de canal est en mode lecture d’octets.

[out, optional] lpCurInstances

Pointeur vers une variable qui reçoit le nombre d’instances de canal actuelles. Ce paramètre peut être NULL si ces informations ne sont pas requises.

[out, optional] lpMaxCollectionCount

Pointeur vers une variable qui reçoit le nombre maximal d’octets à collecter sur l’ordinateur du client avant la transmission au serveur. Ce paramètre doit être NULL si le handle de canal spécifié se trouve à l’extrémité du serveur d’un canal nommé ou si les processus client et serveur se trouvent sur le même ordinateur. Ce paramètre peut être NULL si ces informations ne sont pas requises.

[out, optional] lpCollectDataTimeout

Pointeur vers une variable qui reçoit la durée maximale, en millisecondes, qui peut passer avant qu’un canal nommé distant transfère des informations sur le réseau. Ce paramètre doit être NULL si le handle de canal spécifié se trouve à l’extrémité du serveur d’un canal nommé ou si les processus client et serveur se trouvent sur le même ordinateur. Ce paramètre peut être NULL si ces informations ne sont pas requises.

[out, optional] lpUserName

Pointeur vers une mémoire tampon qui reçoit la chaîne de nom d’utilisateur associée à l’application cliente. Le serveur ne peut récupérer ces informations que si le client a ouvert le canal avec SECURITY_IMPERSONATION accès.

Ce paramètre doit être NULL si le handle de canal spécifié se trouve à l’extrémité cliente d’un canal nommé. Ce paramètre peut être NULL si ces informations ne sont pas requises.

[in] nMaxUserNameSize

Taille de la mémoire tampon spécifiée par le paramètre lpUserName , dans les TCHAR. Ce paramètre est ignoré si lpUserName a la valeur NULL.

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 GetNamedPipeHandleState retourne correctement même si tous les pointeurs qui lui sont passés sont NULL.

Pour définir l’état du handle de canal, utilisez la fonction SetNamedPipeHandleState .

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	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

Fonctions de canal

Vue d’ensemble des canaux

SetNamedPipeHandleState

Share via