Функция CreateNamedPipeA (winbase.h)
Создает экземпляр именованного канала и возвращает дескриптор для последующих операций конвейера. Процесс сервера именованного канала использует эту функцию либо для создания первого экземпляра определенного именованного канала и установки его базовых атрибутов, либо для создания нового экземпляра существующего именованного канала.
Синтаксис
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 или флагов, перечисленных в следующих таблицах.
Этот параметр должен указывать один из следующих режимов доступа к каналу. Для каждого экземпляра канала необходимо указать один и тот же режим.
| Режим | Значение |
|---|---|
|
Канал двунаправленный; Как серверные, так и клиентские процессы могут считывать данные из канала и записывать их в канал. Этот режим предоставляет серверу эквивалент GENERIC_READ и GENERIC_WRITE доступ к каналу. Клиент может указать GENERIC_READ , GENERIC_WRITE или и то, и другое при подключении к каналу с помощью функции CreateFile . |
|
Поток данных в канале передается только от клиента к серверу. Этот режим предоставляет серверу эквивалент GENERIC_READ доступ к каналу. Клиент должен указать GENERIC_WRITE доступа при подключении к каналу. Если клиенту необходимо считывать параметры канала путем вызова функций GetNamedPipeInfo или GetNamedPipeHandleState , клиент должен указать GENERIC_WRITE и FILE_READ_ATTRIBUTES доступа при подключении к каналу. |
|
Поток данных в канале передается только от сервера к клиенту. Этот режим предоставляет серверу эквивалент GENERIC_WRITE доступ к каналу. Клиент должен указать GENERIC_READ доступа при подключении к каналу. Если клиенту необходимо изменить параметры канала, вызвав функцию SetNamedPipeHandleState , клиент должен указать GENERIC_READ и FILE_WRITE_ATTRIBUTES доступа при подключении к каналу. |
Этот параметр также может включать один или несколько следующих флагов, которые позволяют выполнять сквозную запись и перекрывающиеся режимы. Эти режимы могут быть разными для разных экземпляров одного канала.
| Режим | Значение |
|---|---|
|
При попытке создать несколько экземпляров канала с этим флагом создание первого экземпляра завершается успешно, но создание следующего экземпляра завершается сбоем с ERROR_ACCESS_DENIED. |
|
Включен режим сквозной записи. Этот режим влияет только на операции записи в каналы байтового типа, а затем только в том случае, если клиентские и серверные процессы находятся на разных компьютерах. Если этот режим включен, функции, записываемые в именованный канал, не возвращаются, пока записанные данные не будут переданы по сети и не будут помещены в буфер канала на удаленном компьютере. Если этот режим не включен, система повышает эффективность сетевых операций, буферизируя данные до тех пор, пока не накопится минимальное количество байтов или пока не истечет максимальное время. |
|
Режим перекрытия включен. Если этот режим включен, функции, выполняющие операции чтения, записи и подключения, которые могут занять значительное время, могут вернуться немедленно. Этот режим позволяет потоку, запустив операцию, выполнять другие операции, в то время как трудоемкая операция выполняется в фоновом режиме. Например, в режиме перекрытия поток может обрабатывать одновременные операции ввода-вывода (I/O) на нескольких экземплярах канала или выполнять одновременные операции чтения и записи с одного дескриптора канала. Если режим перекрытия не включен, функции, выполняющие операции чтения, записи и подключения в дескрипторе канала, не возвращаются до завершения операции. Функции ReadFileEx и WriteFileEx можно использовать только с дескриптором канала в режиме перекрытия. Функции ReadFile, WriteFile, ConnectNamedPipe и TransactNamedPipe могут выполняться синхронно или как перекрывающиеся операции. |
Этот параметр может включать любое сочетание следующих режимов доступа безопасности. Эти режимы могут быть разными для разных экземпляров одного канала.
| Режим | Значение |
|---|---|
|
Вызывающий объект будет иметь доступ на запись к списку управления доступом (ACL) именованного канала. |
|
Вызывающий объект будет иметь доступ на запись к владельцу именованного канала. |
|
Вызывающий объект будет иметь доступ на запись к SACL именованного канала. Дополнительные сведения см. в разделах Access-Control Списки (ACL) и Права доступа к SACL. |
[in] dwPipeMode
Режим канала.
Функция завершается ошибкой, если dwPipeMode указывает что-либо, кроме 0 или флагов, перечисленных в следующих таблицах.
Можно указать один из следующих режимов типов. Для каждого экземпляра канала необходимо указать один и тот же режим типа.
| Режим | Значение |
|---|---|
|
Данные записываются в канал в виде потока байтов. Этот режим нельзя использовать с PIPE_READMODE_MESSAGE. Канал не различает байты, записанные во время различных операций записи. |
|
Данные записываются в канал в виде потока сообщений. Канал обрабатывает байты, записанные во время каждой операции записи, как единицу сообщения. Функция GetLastError возвращает ERROR_MORE_DATA , если сообщение прочитано не полностью. Этот режим можно использовать с PIPE_READMODE_MESSAGE или PIPE_READMODE_BYTE. |
Можно указать один из следующих режимов чтения. Разные экземпляры одного канала могут указывать разные режимы чтения.
Можно указать один из следующих режимов ожидания. Разные экземпляры одного канала могут указывать разные режимы ожидания.
| Режим | Значение |
|---|---|
|
Режим блокировки включен. Если дескриптор канала указан в функции ReadFile, WriteFile или ConnectNamedPipe , операции не выполняются до тех пор, пока не будет данных для чтения, записи всех данных или подключения клиента. Использование этого режима может означать неограниченное ожидание в некоторых ситуациях, когда клиентский процесс выполнит действие. |
|
Режим неблокировки включен. В этом режиме ReadFile, WriteFile и ConnectNamedPipe всегда возвращаются немедленно.
Обратите внимание, что режим неблокировки поддерживается для совместимости с Microsoft LAN Manager версии 2.0 и не должен использоваться для асинхронного ввода-вывода с помощью именованных каналов. Дополнительные сведения об асинхронном вводе-выводе по каналу см. в разделе Синхронные и перекрывающиеся входные и выходные данные. |
Можно указать один из следующих режимов удаленного клиента. Разные экземпляры одного канала могут указывать разные режимы удаленного клиента.
[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 |