Функция CreateNamedPipeA (winbase.h)

Статья
03/08/2023

Создает экземпляр именованного канала и возвращает дескриптор для последующих операций конвейера. Процесс сервера именованного канала использует эту функцию либо для создания первого экземпляра определенного именованного канала и установки его базовых атрибутов, либо для создания нового экземпляра существующего именованного канала.

Синтаксис

HANDLE CreateNamedPipeA(
  [in]           LPCSTR                lpName,
  [in]           DWORD                 dwOpenMode,
  [in]           DWORD                 dwPipeMode,
  [in]           DWORD                 nMaxInstances,
  [in]           DWORD                 nOutBufferSize,
  [in]           DWORD                 nInBufferSize,
  [in]           DWORD                 nDefaultTimeOut,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Параметры

[in] lpName

Уникальное имя канала. Эта строка должна иметь следующую форму:

\\.\pipe\pipename

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

[in] dwOpenMode

Режим открытия.

Функция завершается сбоем, если dwOpenMode указывает что-либо, кроме 0 или флагов, перечисленных в следующих таблицах.

Этот параметр должен указывать один из следующих режимов доступа к каналу. Для каждого экземпляра канала необходимо указать один и тот же режим.

Режим	Значение
PIPE_ACCESS_DUPLEX 0x00000003	Канал двунаправленный; Как серверные, так и клиентские процессы могут считывать данные из канала и записывать их в канал. Этот режим предоставляет серверу эквивалент GENERIC_READ и GENERIC_WRITE доступ к каналу. Клиент может указать GENERIC_READ , GENERIC_WRITE или и то, и другое при подключении к каналу с помощью функции CreateFile .
PIPE_ACCESS_INBOUND 0x00000001	Поток данных в канале передается только от клиента к серверу. Этот режим предоставляет серверу эквивалент GENERIC_READ доступ к каналу. Клиент должен указать GENERIC_WRITE доступа при подключении к каналу. Если клиенту необходимо считывать параметры канала путем вызова функций GetNamedPipeInfo или GetNamedPipeHandleState , клиент должен указать GENERIC_WRITE и FILE_READ_ATTRIBUTES доступа при подключении к каналу.
PIPE_ACCESS_OUTBOUND 0x00000002	Поток данных в канале передается только от сервера к клиенту. Этот режим предоставляет серверу эквивалент GENERIC_WRITE доступ к каналу. Клиент должен указать GENERIC_READ доступа при подключении к каналу. Если клиенту необходимо изменить параметры канала, вызвав функцию SetNamedPipeHandleState , клиент должен указать GENERIC_READ и FILE_WRITE_ATTRIBUTES доступа при подключении к каналу.

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

Режим	Значение
FILE_FLAG_FIRST_PIPE_INSTANCE 0x00080000	При попытке создать несколько экземпляров канала с этим флагом создание первого экземпляра завершается успешно, но создание следующего экземпляра завершается сбоем с ERROR_ACCESS_DENIED.
FILE_FLAG_WRITE_THROUGH 0x80000000	Включен режим сквозной записи. Этот режим влияет только на операции записи в каналы байтового типа, а затем только в том случае, если клиентские и серверные процессы находятся на разных компьютерах. Если этот режим включен, функции, записываемые в именованный канал, не возвращаются, пока записанные данные не будут переданы по сети и не будут помещены в буфер канала на удаленном компьютере. Если этот режим не включен, система повышает эффективность сетевых операций, буферизируя данные до тех пор, пока не накопится минимальное количество байтов или пока не истечет максимальное время.
FILE_FLAG_OVERLAPPED 0x40000000	Режим перекрытия включен. Если этот режим включен, функции, выполняющие операции чтения, записи и подключения, которые могут занять значительное время, могут вернуться немедленно. Этот режим позволяет потоку, запустив операцию, выполнять другие операции, в то время как трудоемкая операция выполняется в фоновом режиме. Например, в режиме перекрытия поток может обрабатывать одновременные операции ввода-вывода (I/O) на нескольких экземплярах канала или выполнять одновременные операции чтения и записи с одного дескриптора канала. Если режим перекрытия не включен, функции, выполняющие операции чтения, записи и подключения в дескрипторе канала, не возвращаются до завершения операции. Функции ReadFileEx и WriteFileEx можно использовать только с дескриптором канала в режиме перекрытия. Функции ReadFile, WriteFile, ConnectNamedPipe и TransactNamedPipe могут выполняться синхронно или как перекрывающиеся операции.

Этот параметр может включать любое сочетание следующих режимов доступа безопасности. Эти режимы могут быть разными для разных экземпляров одного канала.

Режим	Значение
WRITE_DAC 0x00040000L	Вызывающий объект будет иметь доступ на запись к списку управления доступом (ACL) именованного канала.
WRITE_OWNER 0x00080000L	Вызывающий объект будет иметь доступ на запись к владельцу именованного канала.
ACCESS_SYSTEM_SECURITY 0x01000000L	Вызывающий объект будет иметь доступ на запись к SACL именованного канала. Дополнительные сведения см. в разделах Access-Control Списки (ACL) и Права доступа к SACL.

[in] dwPipeMode

Режим канала.

Функция завершается ошибкой, если dwPipeMode указывает что-либо, кроме 0 или флагов, перечисленных в следующих таблицах.

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

Режим	Значение
PIPE_TYPE_BYTE 0x00000000	Данные записываются в канал в виде потока байтов. Этот режим нельзя использовать с PIPE_READMODE_MESSAGE. Канал не различает байты, записанные во время различных операций записи.
PIPE_TYPE_MESSAGE 0x00000004	Данные записываются в канал в виде потока сообщений. Канал обрабатывает байты, записанные во время каждой операции записи, как единицу сообщения. Функция GetLastError возвращает ERROR_MORE_DATA , если сообщение прочитано не полностью. Этот режим можно использовать с PIPE_READMODE_MESSAGE или PIPE_READMODE_BYTE.

Режим

Значение

PIPE_TYPE_BYTE
0x00000000

Данные записываются в канал в виде потока байтов. Этот режим нельзя использовать с PIPE_READMODE_MESSAGE. Канал не различает байты, записанные во время различных операций записи.

PIPE_TYPE_MESSAGE
0x00000004

Данные записываются в канал в виде потока сообщений. Канал обрабатывает байты, записанные во время каждой операции записи, как единицу сообщения. Функция GetLastError возвращает ERROR_MORE_DATA , если сообщение прочитано не полностью. Этот режим можно использовать с PIPE_READMODE_MESSAGE или PIPE_READMODE_BYTE.

Можно указать один из следующих режимов чтения. Разные экземпляры одного канала могут указывать разные режимы чтения.

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

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

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

Режим

Значение

PIPE_WAIT
0x00000000

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

PIPE_NOWAIT
0x00000001

Режим неблокировки включен. В этом режиме ReadFile, WriteFile и ConnectNamedPipe всегда возвращаются немедленно.

Обратите внимание, что режим неблокировки поддерживается для совместимости с Microsoft LAN Manager версии 2.0 и не должен использоваться для асинхронного ввода-вывода с помощью именованных каналов. Дополнительные сведения об асинхронном вводе-выводе по каналу см. в разделе Синхронные и перекрывающиеся входные и выходные данные.

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

Режим	Значение
PIPE_ACCEPT_REMOTE_CLIENTS 0x00000000	Connections от удаленных клиентов можно принять и проверить на соответствие дескриптору безопасности для канала.
PIPE_REJECT_REMOTE_CLIENTS 0x00000008	Connections от удаленных клиентов автоматически отклоняются.

[in] nMaxInstances

Максимальное число экземпляров, которые можно создать для этого канала. Первый экземпляр канала может указать это значение; для других экземпляров канала необходимо указать то же число. Допустимые значения находятся в диапазоне от 1 до PIPE_UNLIMITED_INSTANCES (255).

Если этот параметр имеет значение PIPE_UNLIMITED_INSTANCES, количество создаваемых экземпляров канала ограничивается только доступностью системных ресурсов. Если nMaxInstances больше PIPE_UNLIMITED_INSTANCES, возвращаемое значение будет INVALID_HANDLE_VALUE , а GetLastError возвращает ERROR_INVALID_PARAMETER.

[in] nOutBufferSize

Количество байтов, зарезервированных для выходного буфера. Обсуждение размера буферов именованных каналов см. в следующем разделе Примечаний.

[in] nInBufferSize

Количество байтов, зарезервированных для входного буфера. Обсуждение размера буферов именованных каналов см. в следующем разделе Примечаний.

[in] nDefaultTimeOut

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

Значение, равное нулю, приведет к истечению времени ожидания по умолчанию в 50 миллисекундах.

[in, optional] lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , которая задает дескриптор безопасности для нового именованного канала и определяет, могут ли дочерние процессы наследовать возвращаемый дескриптор. Если lpSecurityAttributes имеет значение NULL, именованный канал получает дескриптор безопасности по умолчанию и дескриптор не может быть унаследован. Списки управления доступом в дескрипторе безопасности по умолчанию для именованного канала предоставляют полный контроль учетной записи LocalSystem, администраторам и владельцу создателя. Они также предоставляют доступ на чтение членам группы Все и анонимной учетной записи.

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

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

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

Чтобы создать экземпляр именованного канала с помощью CreateNamedPipe, пользователь должен иметь FILE_CREATE_PIPE_INSTANCE доступ к объекту именованного канала. Если создается новый именованный канал, список управления доступом (ACL) из параметра атрибутов безопасности определяет управление доступом на уровне пользователей для именованного канала.

Все экземпляры именованного канала должны указывать один и тот же тип канала (байтовый тип или тип сообщения), доступ к каналу (дуплексный, входящий или исходящий), число экземпляров и значение времени ожидания. Если используются разные значения, эта функция завершается сбоем, и GetLastError возвращает ERROR_ACCESS_DENIED.

Клиентский процесс подключается к именованной трубе с помощью функции CreateFile или CallNamedPipe . Клиентская часть именованного канала запускается в режиме байтов, даже если сервер находится в режиме сообщений. Чтобы избежать проблем с получением данных, также установите на стороне клиента режим сообщений. Чтобы изменить режим канала, клиент канала должен открыть канал только для чтения с GENERIC_READ и FILE_WRITE_ATTRIBUTES доступом.

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

При каждом создании именованного канала система создает входящий и (или) исходящий буферы с помощью пула без паха, который представляет собой физическую память, используемую ядром. Количество экземпляров канала (а также объектов, таких как потоки и процессы), которые можно создать, ограничено доступным пулом без паха. Для каждого запроса на чтение или запись требуется место в буфере для чтения или записи данных, а также дополнительное пространство для внутренних структур данных.

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

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

Чтобы освободить ресурсы, используемые именованным каналом, приложение всегда должно закрывать дескрипторы, когда они больше не нужны, что выполняется путем вызова функции CloseHandle или при завершении процесса, связанного с дескриптором экземпляра. Обратите внимание, что экземпляр именованного канала может иметь несколько связанных с ним дескрипторов. Экземпляр именованного канала всегда удаляется при закрытии последнего дескриптора экземпляра именованного канала.

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

Примеры

Пример см. в разделе Многопоточный сервер канала.

Требования

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