Funzione TransactNamedPipe (namedpipeapi.h)

Articolo
02/29/2024

Combina le funzioni a cui scrivere un messaggio e leggere un messaggio dalla pipe denominata specificata in un'unica operazione.

Sintassi

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
);

Parametri

[in] hNamedPipe

Handle alla pipe denominata restituita dalla funzione CreateNamedPipe o CreateFile .

Questo parametro può anche essere un handle per una pipe anonima, come restituito dalla funzione CreatePipe .

[in] lpInBuffer

Puntatore al buffer contenente i dati da scrivere nella pipe.

[in] nInBufferSize

Dimensioni del buffer di input, in byte.

[out] lpOutBuffer

Puntatore al buffer che riceve i dati letti dalla pipe.

[in] nOutBufferSize

Dimensioni in byte del buffer di output.

[out] lpBytesRead

Puntatore alla variabile che riceve il numero di byte letti dalla pipe.

Se lpOverlapped è NULL, lpBytesRead non può essere NULL.

Se lpOverlapped non è NULL, lpBytesRead può essere NULL. Se si tratta di un'operazione di lettura sovrapposta, è possibile ottenere il numero di byte letti chiamando GetOverlappedResult. Se hNamedPipe è associato a una porta di completamento di I/O, è possibile ottenere il numero di byte letti chiamando GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Puntatore a una struttura OVERLAPPED . Questa struttura è necessaria se hNamedPipe è stato aperto con FILE_FLAG_OVERLAPPED.

Se hNamedPipe è stato aperto con FILE_FLAG_OVERLAPPED, il parametro lpOverlapped non deve essere NULL. Deve puntare a una struttura OVERLAPPED valida. Se hNamedPipe è stato creato con FILE_FLAG_OVERLAPPED e lpOverlapped è NULL, la funzione può segnalare in modo errato che l'operazione sia stata completata.

Se hNamedPipe è stato aperto con FILE_FLAG_OVERLAPPED e lpOverlapped non è NULL, TransactNamedPipe viene eseguito come operazione sovrapposta. La struttura OVERLAPPED deve contenere un oggetto evento di reimpostazione manuale , che può essere creato usando la funzione CreateEvent . Se l'operazione non può essere completata immediatamente, TransactNamedPipe restituisce FALSE e GetLastError restituisce ERROR_IO_PENDING. In questa situazione, l'oggetto evento viene impostato sullo stato non assegnato prima che TransactNamedPipe restituisca e venga impostato sullo stato segnalato al termine della transazione. È anche possibile ricevere una notifica quando viene completata un'operazione sovrapposta usando le funzioni GetQueuedCompletionStatus o GetQueuedCompletionStatusEx. In questo caso, non è necessario assegnare l'evento di reimpostazione manuale nella struttura OVERLAPPED e il completamento si verifica con hNamedPipe nello stesso modo di un'operazione di lettura o scrittura asincrona. Per altre informazioni sulle operazioni sovrapposte, vedere Pipe.

Se hNamedPipe non è stato aperto con FILE_FLAG_OVERLAPPED, TransactNamedPipe non restituisce fino al completamento dell'operazione.

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.

Se il messaggio da leggere è più lungo del buffer specificato dal parametro nOutBufferSize , TransactNamedPipe restituisce FALSE e la funzione GetLastError restituisce ERROR_MORE_DATA. Il resto del messaggio può essere letto da una chiamata successiva a ReadFile, ReadFileEx o PeekNamedPipe.

Commenti

TransactNamedPipe ha esito negativo se il server non ha creato la pipe come pipe di tipo messaggio o se l'handle della pipe non è in modalità di lettura messaggi. Ad esempio, se un client è in esecuzione nello stesso computer del server e usa il formato \.\pipename per aprire la pipe, la pipe viene aperta in modalità byte dal file system di pipe denominato (NPFS). Se il client usa il modulo \\server\pipe\pipename, il reindirizzamento apre la pipe in modalità messaggio. Un handle pipe in modalità byte può essere modificato in modalità di lettura messaggio con la funzione SetNamedPipeHandleState .

La funzione non può essere completata correttamente finché i dati non sono scritti nel buffer specificato dal parametro lpOutBuffer . Il parametro lpOverlapped è disponibile per consentire al thread chiamante di eseguire altre attività durante l'esecuzione dell'operazione in background.

La dimensione massima garantita di una transazione pipe denominata è di 64 kilobyte. In alcuni casi, le transazioni oltre 64 kilobyte sono possibili, a seconda delle versioni del sistema operativo che partecipano alle condizioni di transazione e di rete dinamica. Tuttavia, non esiste alcuna garanzia che le transazioni superiori a 64 kilobyte avranno esito positivo. È pertanto consigliabile che le transazioni pipe denominate siano limitate a 64 kilobyte di dati.

Windows 10 versione 1709: i pipe sono supportati solo all'interno di un contenitore di app, ovvero da un processo UWP a un altro processo UWP che fa parte della stessa app. Inoltre, i pipe denominati devono usare la sintassi \\.\pipe\LOCAL\ per il nome della pipe.

Esempio

Per un esempio, vedere Transazioni in Named Pipe.

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