TransactNamedPipe-Funktion (namedpipeapi.h)

Artikel
03/06/2024

Kombiniert die Funktionen, die eine Nachricht in schreiben, und liest eine Nachricht aus der angegebenen Named Pipe in einem einzelnen Vorgang.

Syntax

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

Parameter

[in] hNamedPipe

Ein Handle für die Named Pipe, die von der CreateNamedPipe - oder CreateFile-Funktion zurückgegeben wird.

Dieser Parameter kann auch ein Handle für eine anonyme Pipe sein, wie von der CreatePipe-Funktion zurückgegeben.

[in] lpInBuffer

Ein Zeiger auf den Puffer, der die Daten enthält, die in die Pipe geschrieben werden sollen.

[in] nInBufferSize

Die Größe des Eingabepuffers in Bytes.

[out] lpOutBuffer

Ein Zeiger auf den Puffer, der die aus der Pipe gelesenen Daten empfängt.

[in] nOutBufferSize

Die Größe des Ausgabepuffers in Bytes.

[out] lpBytesRead

Ein Zeiger auf die Variable, die die Anzahl der aus der Pipe gelesenen Bytes empfängt.

Wenn lpOverlappedNULL ist, kann lpBytesRead nicht NULL sein.

Wenn lpOverlapped nicht NULL ist, kann lpBytesReadNULL sein. Wenn dies ein überlappender Lesevorgang ist, können Sie die Anzahl der gelesenen Bytes abrufen, indem Sie GetOverlappedResult aufrufen. Wenn hNamedPipe einem E/A-Abschlussport zugeordnet ist, können Sie die Anzahl der gelesenen Bytes abrufen, indem Sie GetQueuedCompletionStatus aufrufen.

[in, out, optional] lpOverlapped

Ein Zeiger auf eine Struktur OVERLAPPED. Diese Struktur ist erforderlich, wenn hNamedPipe mit FILE_FLAG_OVERLAPPED geöffnet wurde.

Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED geöffnet wurde, darf der lpOverlapped-Parameter nicht NULL sein. Sie muss auf eine gültige OVERLAPPED-Struktur verweisen. Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED erstellt wurde und lpOverlappedNULL ist, kann die Funktion fälschlicherweise melden, dass der Vorgang abgeschlossen ist.

Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED geöffnet wurde und lpOverlapped nicht NULL ist, wird TransactNamedPipe als überlappender Vorgang ausgeführt. Die OVERLAPPED-Struktur sollte ein Ereignisobjekt für manuelles Zurücksetzen enthalten (das mit der CreateEvent-Funktion erstellt werden kann). Wenn der Vorgang nicht sofort abgeschlossen werden kann, gibt TransactNamedPipeFALSE und GetLastError ERROR_IO_PENDING zurück. In diesem Fall wird das Ereignisobjekt auf den nicht signalierten Zustand festgelegt, bevor TransactNamedPipe zurückgibt, und es wird auf den signalierten Zustand festgelegt, wenn die Transaktion abgeschlossen ist. Außerdem können Sie benachrichtigt werden, wenn ein überlappender Vorgang abgeschlossen wird, indem Sie die Funktionen GetQueuedCompletionStatus oder GetQueuedCompletionStatusEx verwenden. In diesem Fall müssen Sie das Ereignis für manuelles Zurücksetzen nicht in der OVERLAPPED-Struktur zuweisen, und die Vervollständigung erfolgt für hNamedPipe auf die gleiche Weise wie bei einem asynchronen Lese- oder Schreibvorgang. Weitere Informationen zu überlappenden Vorgängen finden Sie unter Pipes.

Wenn hNamedPipe nicht mit FILE_FLAG_OVERLAPPED geöffnet wurde, wird TransactNamedPipe erst zurückgegeben, wenn der Vorgang abgeschlossen ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn die zu lesende Nachricht länger als der durch den nOutBufferSize-Parameter angegebene Puffer ist, gibt TransactNamedPipeFALSE zurück, und die GetLastError-Funktion gibt ERROR_MORE_DATA zurück. Der Rest der Nachricht kann durch einen nachfolgenden Aufruf von ReadFile, ReadFileEx oder PeekNamedPipe gelesen werden.

Hinweise

TransactNamedPipe schlägt fehl, wenn der Server die Pipe nicht als Nachrichtentyppipe erstellt hat oder sich das Pipehandle nicht im Nachrichtenlesemodus befindet. Wenn beispielsweise ein Client auf demselben Computer wie der Server ausgeführt wird und das Format \.\pipe\pipename zum Öffnen der Pipe verwendet, wird die Pipe im Bytemodus vom Named Pipe File System (NPFS) geöffnet. Wenn der Client das Format \\server\pipe\pipename verwendet, öffnet der Redirector die Pipe im Nachrichtenmodus. Ein Pipehandle im Bytemodus kann mit der SetNamedPipeHandleState-Funktion in den Nachrichtenlesemodus geändert werden.

Die Funktion kann erst erfolgreich abgeschlossen werden, wenn Die Daten in den durch den lpOutBuffer-Parameter angegebenen Puffer geschrieben wurden. Der parameter lpOverlapped ist verfügbar, damit der aufrufende Thread andere Aufgaben ausführen kann, während der Vorgang im Hintergrund ausgeführt wird.

Die maximale garantierte Größe einer Named Pipe-Transaktion beträgt 64 KB. In einigen begrenzten Fällen sind Transaktionen über 64 KB möglich, abhängig von den betriebssystemalen Versionen, die an der Transaktion teilnehmen, und dynamischen Netzwerkbedingungen. Es gibt jedoch keine Garantie, dass Transaktionen über 64 KB erfolgreich sind. Daher wird empfohlen, dass Named Pipe-Transaktionen auf 64 KB An Daten beschränkt werden.

Windows 10 Version 1709: Pipes werden nur innerhalb eines App-Containers unterstützt, d. h. von einem UWP-Prozess zu einem anderen UWP-Prozess, der Teil derselben App ist. Außerdem müssen Named Pipes die Syntax \\.\pipe\LOCAL\ für den Pipenamen verwenden.

Beispiele

Ein Beispiel finden Sie unter Transaktionen in Named Pipes.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	namedpipeapi.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll