Функция TransactNamedPipe (namedpipeapi.h)

Статья
03/08/2023

Объединяет функции, которые записывают сообщение в и считывают сообщение из указанного именованного канала, в одну операцию.

Синтаксис

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

Параметры

[in] hNamedPipe

Дескриптор именованного канала, возвращаемого функцией CreateNamedPipe или CreateFile .

Этот параметр также может быть дескриптором анонимного канала, возвращаемого функцией CreatePipe .

[in] lpInBuffer

Указатель на буфер, содержащий данные для записи в канал.

[in] nInBufferSize

Размер входного буфера в байтах.

[out] lpOutBuffer

Указатель на буфер, который получает данные, считываемые из канала.

[in] nOutBufferSize

Размер выходного буфера в байтах.

[out] lpBytesRead

Указатель на переменную, которая получает число байтов, считанных из канала.

Если lpOverlapped имеет значение NULL, lpBytesRead не может иметь значение NULL.

Если lpOverlapped не равно NULL, lpBytesRead может иметь значение NULL. Если это перекрываемая операция чтения, можно получить количество считываемых байтов, вызвав Метод GetOverlappedResult. Если hNamedPipe связан с портом завершения ввода-вывода, количество прочитанных байтов можно получить, вызвав GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Указатель на структуру OVERLAPPED . Эта структура необходима, если hNamedPipe был открыт с FILE_FLAG_OVERLAPPED.

Если hNamedPipe был открыт с FILE_FLAG_OVERLAPPED, параметр lpOverlapped не должен иметь значение NULL. Он должен указывать на допустимую структуру OVERLAPPED . Если hNamedPipe был создан с FILE_FLAG_OVERLAPPED и lpOverlapped имеет значение NULL, функция может неправильно сообщить, что операция завершена.

Если hNamedPipe был открыт с FILE_FLAG_OVERLAPPED и lpOverlapped не имеет значение NULL, TransactNamedPipe выполняется как перекрываемая операция. Структура OVERLAPPED должна содержать объект события сброса вручную (который можно создать с помощью функции CreateEvent ). Если операция не может быть завершена немедленно, TransactNamedPipe возвращает значение FALSE , а GetLastError — ERROR_IO_PENDING. В этом случае объекту события присваивается состояние nonsignaled до возврата TransactNamedPipe , а по завершении транзакции устанавливается состояние сигнала. Кроме того, вы можете получать уведомления о завершении перекрываемой операции с помощью функций GetQueuedCompletionStatus или GetQueuedCompletionStatusEx . В этом случае не нужно назначать событие сброса вручную в структуре OVERLAPPED , а завершение выполняется для hNamedPipe так же, как асинхронная операция чтения или записи. Дополнительные сведения о перекрывающихся операциях см. в разделе Каналы.

Если hNamedPipe не был открыт с FILE_FLAG_OVERLAPPED, TransactNamedPipe не возвращается до завершения операции.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Если считываемое сообщение длиннее буфера, заданного параметром nOutBufferSize , TransactNamedPipe возвращает значение FALSE , а функция GetLastError возвращает ERROR_MORE_DATA. Оставшаяся часть сообщения может быть прочитана последующим вызовом ReadFile, ReadFileEx или PeekNamedPipe.

TransactNamedPipe завершается ошибкой , если сервер не создавал канал как канал типа сообщения или дескриптор канала не находится в режиме чтения сообщений. Например, если клиент работает на том же компьютере, что и сервер, и использует формат \.\pipe\pipename для открытия канала, канал открывается в режиме байтов файловой системой именованного канала (NPFS). Если клиент использует форму \\server\pipe\pipename, перенаправитель открывает канал в режиме сообщения. Дескриптор канала в режиме байтов можно изменить на режим чтения сообщений с помощью функции SetNamedPipeHandleState .

Функция не может быть успешно завершена, пока данные не будут записаны в буфер, указанный параметром lpOutBuffer . Параметр lpOverlapped доступен для того, чтобы вызывающий поток мог выполнять другие задачи во время выполнения операции в фоновом режиме.

Максимальный гарантированный размер транзакции именованного канала составляет 64 килобайта. В некоторых ограниченных случаях возможны транзакции, превышающие 64 килобайта, в зависимости от версий ОС, участвующих в транзакциях и динамических сетевых условиях. Однако нет никакой гарантии, что транзакции свыше 64 килобайт будут успешными. Поэтому рекомендуется ограничить транзакции именованного канала до 64 килобайт данных.

Windows 10 версии 1709: каналы поддерживаются только в контейнере приложений, т. е. от одного процесса UWP к другому процессу UWP, который является частью того же приложения. Кроме того, именованные каналы должны использовать синтаксис \\.\pipe\LOCAL\ для имени канала.

Примеры

Пример см. в разделе Транзакции по именованным каналам.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	namedpipeapi.h
Библиотека	Kernel32.lib
DLL	Kernel32.dll