TransactNamedPipe, fonction (namedpipeapi.h)

Article
03/04/2024

Combine les fonctions qui écrivent un message dans et lisent un message à partir du canal nommé spécifié en une seule opération.

Syntaxe

BOOL TransactNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in]                LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out]               LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out]               LPDWORD      lpBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hNamedPipe

Handle du canal nommé retourné par la fonction CreateNamedPipe ou CreateFile .

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

[in] lpInBuffer

Pointeur vers la mémoire tampon contenant les données à écrire dans le canal.

[in] nInBufferSize

Taille, en octets, de la mémoire tampon d’entrée.

[out] lpOutBuffer

Pointeur vers la mémoire tampon qui reçoit les données lues à partir du canal.

[in] nOutBufferSize

Taille de la mémoire tampon de sortie en octets.

[out] lpBytesRead

Pointeur vers la variable qui reçoit le nombre d’octets lus à partir du canal.

Si lpOverlapped a la valeur NULL, lpBytesRead ne peut pas être NULL.

Si lpOverlapped n’a pas la valeur NULL, lpBytesRead peut être NULL. S’il s’agit d’une opération de lecture qui se chevauche, vous pouvez obtenir le nombre d’octets lus en appelant GetOverlappedResult. Si hNamedPipe est associé à un port d’achèvement des E/S, vous pouvez obtenir le nombre d’octets lus en appelant GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Pointeur vers une structure OVERLAPPED. Cette structure est requise si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED.

Si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED, le paramètre lpOverlapped ne doit pas être NULL. Il doit pointer vers une structure CHEVAUCHEMENT VALIDE . Si hNamedPipe a été créé avec FILE_FLAG_OVERLAPPED et que lpOverlapped a la valeur NULL, la fonction peut signaler à tort que l’opération est terminée.

Si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED et que lpOverlapped n’a pas la valeur NULL, TransactNamedPipe est exécuté comme une opération qui se chevauche. La structure OVERLAPPED doit contenir un objet d’événement de réinitialisation manuelle (qui peut être créé à l’aide de la fonction CreateEvent ). Si l’opération ne peut pas être effectuée immédiatement, TransactNamedPipe renvoie FALSE et GetLastError renvoie ERROR_IO_PENDING. Dans ce cas, l’objet d’événement est défini sur l’état non signé avant le retour de TransactNamedPipe , et il est défini sur l’état signalé lorsque la transaction est terminée. En outre, vous pouvez être averti lorsqu’une opération qui se chevauche se termine à l’aide des fonctions GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . Dans ce cas, vous n’avez pas besoin d’affecter l’événement de réinitialisation manuelle dans la structure OVERLAPPED , et l’achèvement se produit sur hNamedPipe de la même façon qu’une opération de lecture ou d’écriture asynchrone. Pour plus d’informations sur les opérations qui se chevauchent, consultez Canaux.

Si hNamedPipe n’a pas été ouvert avec FILE_FLAG_OVERLAPPED, TransactNamedPipe ne retourne pas tant que l’opération n’est pas terminée.

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.

Si le message à lire est plus long que la mémoire tampon spécifiée par le paramètre nOutBufferSize , TransactNamedPipe retourne FALSE et la fonction GetLastError retourne ERROR_MORE_DATA. Le reste du message peut être lu par un appel ultérieur à ReadFile, ReadFileEx ou PeekNamedPipe.

Remarques

TransactNamedPipe échoue si le serveur n’a pas créé le canal en tant que canal de type message ou si le handle de canal n’est pas en mode lecture de message. Par exemple, si un client s’exécute sur la même machine que le serveur et utilise le format \.\pipename\pipename pour ouvrir le canal, le canal est ouvert en mode octet par le système de fichiers de canal nommé (NPFS). Si le client utilise la forme \\server\pipe\pipename, le redirecteur ouvre le canal en mode message. Un handle de canal en mode octet peut être remplacé par le mode de lecture de message avec la fonction SetNamedPipeHandleState .

La fonction ne peut pas être exécutée correctement tant que les données n’ont pas été écrites dans la mémoire tampon spécifiée par le paramètre lpOutBuffer . Le paramètre lpOverlapped est disponible pour permettre au thread appelant d’effectuer d’autres tâches pendant que l’opération s’exécute en arrière-plan.

La taille maximale garantie d’une transaction de canal nommé est de 64 kilo-octets. Dans certains cas limités, les transactions au-delà de 64 kilo-octets sont possibles, en fonction des versions du système d’exploitation participant à la transaction et des conditions réseau dynamiques. Toutefois, il n’existe aucune garantie que les transactions supérieures à 64 kilo-octets réussissent. Par conséquent, il est recommandé de limiter les transactions de canal nommé à 64 kilo-octets de données.

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.

Exemples

Pour obtenir un exemple, consultez Transactions sur des canaux nommés.

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