Функция 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\имя канала
Часть имени канала может включать любой символ, отличный от обратной косой черты, включая цифры и специальные символы. Длина всей строки имени канала может составлять до 256 символов. Имена каналов не учитывает регистр.
[in] dwOpenMode
Открытый режим.
Функция завершается ошибкой, если dwOpenMode указывает что-либо, отличное от 0, или флаги, перечисленные в следующих таблицах.
Этот параметр должен указать один из следующих режимов доступа к каналу. Для каждого экземпляра канала необходимо указать один и тот же режим.
| Режим | Значение |
|---|---|
|
Канал двунаправленный; как серверные, так и клиентские процессы могут считывать и записывать данные в канал. Этот режим предоставляет серверу эквивалент GENERIC_READ и GENERIC_WRITE доступ к каналу. Клиент может указать |
|
Поток данных в канале передается только от клиента к серверу. Этот режим предоставляет серверу эквивалент GENERIC_READ доступ к каналу. Клиент должен указать GENERIC_WRITE доступ при подключении к каналу. Если клиент должен считывать параметры канала, вызвав GetNamedPipeInfo или функции GetNamedPipeHandleState, клиент должен указать GENERIC_WRITE и FILE_READ_ATTRIBUTES доступ при подключении к каналу. |
|
Поток данных в канале передается только с сервера на клиент. Этот режим предоставляет серверу эквивалент GENERIC_WRITE доступ к каналу. Клиент должен указать GENERIC_READ доступ при подключении к каналу. Если клиент должен изменить параметры канала, вызвав функцию SetNamedPipeHandleState, клиент должен указать GENERIC_READ и FILE_WRITE_ATTRIBUTES доступ при подключении к каналу. |
Этот параметр также может включать один или несколько следующих флагов, которые позволяют выполнять операции записи и перекрывающиеся режимы. Эти режимы могут отличаться для разных экземпляров одного канала.
| Режим | Значение |
|---|---|
|
Если вы пытаетесь создать несколько экземпляров канала с этим флагом, создание первого экземпляра завершается успешно, но создание следующего экземпляра завершается сбоем с ERROR_ACCESS_DENIED. |
|
Режим записи включен. Этот режим влияет только на операции записи в каналах типа байтов, а затем, только если процессы клиента и сервера находятся на разных компьютерах. Если этот режим включен, функции, записываемые в именованный канал, не возвращаются до передачи данных через сеть и в буфере канала на удаленном компьютере. Если этот режим не включен, система повышает эффективность сетевых операций путем буферизации данных до минимального количества байтов или до истечения максимального времени. |
|
Режим перекрытия включен. Если этот режим включен, функции, выполняющие операции чтения, записи и подключения, которые могут занять значительное время, можно немедленно вернуть. Этот режим позволяет потоку, запускающем операцию, выполнять другие операции во время выполнения операции с длительным выполнением в фоновом режиме. Например, в перекрываемом режиме поток может обрабатывать одновременные операции ввода-вывода (ввода-вывода) в нескольких экземплярах канала или выполнять одновременные операции чтения и записи в одном дескрипторе канала. Если перекрывающийся режим не включен, функции, выполняющие операции чтения, записи и подключения к дескриптору канала, не возвращаются до завершения операции. Функции ReadFileEx и WriteFileEx можно использовать только с дескриптором канала в перекрываемом режиме. ReadFile, WriteFile, ConnectNamedPipeи Функции TransactNamedPipe могут выполняться синхронно или как перекрывающиеся операции. |
Этот параметр может включать любое сочетание следующих режимов доступа к безопасности. Эти режимы могут отличаться для разных экземпляров одного канала.
[in] dwPipeMode
Режим канала.
Функция завершается ошибкой, если dwPipeMode указывает что-либо, отличное от 0, или флаги, перечисленные в следующих таблицах.
Можно указать один из следующих режимов типа. Для каждого экземпляра канала необходимо указать один и тот же режим типа.
Можно указать один из следующих режимов чтения. Разные экземпляры одного канала могут указывать разные режимы чтения.
Можно указать один из следующих режимов ожидания. Разные экземпляры одного канала могут указывать различные режимы ожидания.
| Режим | Значение |
|---|---|
|
Режим блокировки включен. Если дескриптор канала указан в функции |
|
Режим неблокировки включен. В этом режиме 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
Значение нуля приведет к истечении времени ожидания по умолчанию в 50 миллисекундах.
[in, optional] lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES, которая задает дескриптор безопасности для нового именованного канала и определяет, могут ли дочерние процессы наследовать возвращенный дескриптор. Если lpSecurityAttributesNULL, именованный канал получает дескриптор безопасности по умолчанию и дескриптор безопасности нельзя наследовать. Списки управления доступом в дескрипторе безопасности по умолчанию для именованного канала предоставляют полный контроль учетной записи 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] |
| целевая платформа | Виндоус |
| заголовка | winbase.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |
См. также
Функции
Обзор каналов