Именованный канал

Именованный канал — это именованный односторонний или дуплексный канал для связи между сервером и одним или несколькими клиентами каналов. Все экземпляры именованного канала совместно используют одно и то же имя канала, но каждый экземпляр имеет свои собственные буферы и дескрипторы и обеспечивает отдельный канал для связи клиент-сервер. Использование экземпляров позволяет нескольким клиентам канала одновременно использовать один и тот же именованный канал.

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

Любой процесс может выступать в роли как сервера, так и клиента, что делает возможным одноранговое взаимодействие. Используемый здесь термин «сервер» относится к процессу, который создает именованный канал, а термин «клиент» относится к процессу, который подключается к экземпляру именованного канала. Серверной функцией для создания экземпляра именованного канала является CreateNamedPipe. Серверной функцией для принятия соединения является ConnectNamedPipe. Клиентский процесс подключается к именованному каналу с помощью функции CreateFile или CallNamedPipe.

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

Функция создания именованного канала

HANDLE CreateNamedPipe(

LPCSTR lpName,

DWORD dwOpenMode,

DWORD dwPipeMode,

DWORD nMaxInstances,

DWORD nOutBufferSize,

DWORD nInBufferSize,

DWORD nDefaultTimeOut,

LPSECURITY_ATTRIBUTES lpSecAttr

);

Параметры и описание:

(1) lpName — определяет уникальное название трубы. Эта строка должна иметь следующую форму: \.\pipe<i>pipename

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

(2) dwOpenMode — определяет режим открытия.

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

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

— PIPE_ACCESS_DUPLEX (0x00000003) — канал двунаправленный; как серверные, так и клиентские процессы могут читать и записывать в канал.

— PIPE_ACCESS_INBOUND (0x00000001) — поток данных в канале идет только от клиента к серверу.

— PIPE_ACCESS_OUTBOUND (0x00000002) — поток данных в канале идет только от сервера к клиенту.

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

— 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 именованного канала.

(3) 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_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_ACCEPT_REMOTE_CLIENTS (0x00000000) — соединения от удаленных клиентов могут быть приняты и проверены по дескриптору безопасности для канала.

— PIPE_REJECT_REMOTE_CLIENTS (0x00000008) — подключения от удаленных клиентов автоматически отклоняются.

(4) nMaxInstances — определяет максимальное количество экземпляров, которые могут быть созданы для этого канала. Первый экземпляр канала может указывать это значение; тот же номер должен быть указан для других экземпляров канала. Допустимые значения находятся в диапазоне от 1 до PIPE_UNLIMITED_INSTANCES (255). Если этот параметр равен PIPE_UNLIMITED_INSTANCES, количество создаваемых экземпляров канала может быть ограничено только доступностью системных ресурсов. Если nMaxInstances больше, чем PIPE_UNLIMITED_INSTANCES, возвращаемое значение равно INVALID_HANDLE_VALUE и GetLastError возвращает ERROR_INVALID_PARAMETER.

(5) nOutBufferSize — определяет количество байтов, резервируемых для выходного буфера.

(6) nInBufferSize — определяет количество байтов, зарезервированных для входного буфера.

(7) nDefaultTimeOut — определяет значение времени ожидания по умолчанию в миллисекундах, если функция WaitNamedPipe задает NMPWAIT_USE_DEFAULT_WAIT. Каждый экземпляр именованного канала должен указывать одно и то же значение. При нулевом значении тайм-аут по умолчанию составляет 50 миллисекунд.

(8) lpSecAttr — Указатель на структуру SECURITY_ATTRIBUTES, которая задает дескриптор безопасности для нового именованного канала и определяет, могут ли дочерние процессы наследовать возвращенный дескриптор. Если lpSecAttr имеет значение NULL, именованный канал получает дескриптор безопасности по умолчанию и дескриптор не наследуется.

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

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

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