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

Статья
08/25/2023

Задает режим чтения и режим блокировки указанного именованного канала. Если указанный дескриптор находится на стороне клиента именованного канала и серверный процесс именованного канала находится на удаленном компьютере, функцию также можно использовать для управления локальной буферизацией.

Синтаксис

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Параметры

[in] hNamedPipe

Дескриптор экземпляра именованного канала. Этот параметр может быть дескриптором для серверного конца канала, возвращаемого функцией CreateNamedPipe , или клиентского конца канала, возвращаемого функцией CreateFile . Дескриптор должен иметь GENERIC_WRITE доступ к именованным каналу для канала, доступного только для чтения или записи, либо должен иметь доступ к GENERIC_READ и FILE_WRITE_ATTRIBUTES для канала только для чтения.

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

[in, optional] lpMode

Новый режим канала. Режим представляет собой сочетание флага режима чтения и флага режима ожидания. Этот параметр может иметь значение NULL , если режим не задан. Укажите один из следующих режимов.

Режим	Значение
PIPE_READMODE_BYTE 0x00000000	Данные считываются из канала в виде потока байтов. Этот режим используется по умолчанию, если флаг режима чтения не указан.
PIPE_READMODE_MESSAGE 0x00000002	Данные считываются из канала в виде потока сообщений. Функция завершается ошибкой, если этот флаг указан для канала байтового типа.

Можно указать один из следующих режимов ожидания.

Режим	Значение
PIPE_WAIT 0x00000000	Режим блокировки включен. Этот режим используется по умолчанию, если флаг режима ожидания не указан. Если в функции ReadFile, WriteFile или ConnectNamedPipe указан дескриптор канала режима блокировки, операции не завершаются до тех пор, пока не будут считываемые данные, все данные записываются или не подключен клиент. Использование этого режима в некоторых ситуациях может означать неограниченное ожидание выполнения действия клиентским процессом.
PIPE_NOWAIT 0x00000001	Включен неблокировка. В этом режиме ReadFile, WriteFile и ConnectNamedPipe всегда возвращаются немедленно. Обратите внимание, что режим неблокировки поддерживается для совместимости с Microsoft LAN Manager версии 2.0 и не должен использоваться для асинхронного ввода-вывода (I/O) с именованными каналами.

Режим

Значение

PIPE_WAIT
0x00000000

Режим блокировки включен. Этот режим используется по умолчанию, если флаг режима ожидания не указан. Если в функции ReadFile, WriteFile или ConnectNamedPipe указан дескриптор канала режима блокировки, операции не завершаются до тех пор, пока не будут считываемые данные, все данные записываются или не подключен клиент. Использование этого режима в некоторых ситуациях может означать неограниченное ожидание выполнения действия клиентским процессом.

PIPE_NOWAIT
0x00000001

Включен неблокировка. В этом режиме ReadFile, WriteFile и ConnectNamedPipe всегда возвращаются немедленно. Обратите внимание, что режим неблокировки поддерживается для совместимости с Microsoft LAN Manager версии 2.0 и не должен использоваться для асинхронного ввода-вывода (I/O) с именованными каналами.

[in, optional] lpMaxCollectionCount

Максимальное число байтов, собранных на клиентском компьютере перед передачей на сервер. Этот параметр должен иметь значение NULL , если указанный дескриптор канала находится на серверной стороне именованного канала или если клиентский и серверный процессы находятся на одном компьютере. Этот параметр игнорируется, если клиентский процесс задает флаг FILE_FLAG_WRITE_THROUGH в функции CreateFile при создании дескриптора. Этот параметр может иметь значение NULL , если количество коллекций не задано.

[in, optional] lpCollectDataTimeout

Максимальное время (в миллисекундах), которое может пройти до передачи данных по сети удаленным именованным каналом. Этот параметр должен иметь значение NULL , если указанный дескриптор канала находится на сервере именованного канала или если клиентские и серверные процессы находятся на одном компьютере. Этот параметр игнорируется, если клиентский процесс указал флаг FILE_FLAG_WRITE_THROUGH в функции CreateFile при создании дескриптора. Этот параметр может иметь значение NULL , если количество коллекций не задано.

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

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

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

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

Примеры

Пример см. в разделе Клиент именованного канала.

Требования

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