Функция NtCreateNamedPipeFile

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

Синтаксис

NTSTATUS NtCreateNamedPipeFile(
  [out]          PHANDLE            FileHandle,
  [in]           ULONG              DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in]           ULONG              NamedPipeType,
  [in]           ULONG              ReadMode,
  [in]           ULONG              CompletionMode,
  [in]           ULONG              MaximumInstances,
  [in]           ULONG              InboundQuota,
  [in]           ULONG              OutboundQuota,
  [in, optional] PLARGE_INTEGER     DefaultTimeout
);

Параметры

FileHandle [out]

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

DesiredAccess [in]

Битовая маска флагов, указывающая тип доступа к файлу или каталогу, который требуется вызывающей организации. Этот набор системных флагов DesiredAccess определяет следующие конкретные права доступа для файловых объектов.

Кроме того, для любого объекта файла, который не представляет каталог, можно указать один или несколько следующих общих флагов ACCESS_MASK . Флаги STANDARD_RIGHTS_XXX — это предопределенные системные значения, которые используются для обеспечения безопасности системных объектов. Вы также можете объединить эти универсальные флаги с дополнительными флагами из предыдущей таблицы.

Для каталогов (FILE_DIRECTORY_FILEустановлен флаг CreateOptions) можно указать один или несколько следующих флагов ACCESS_MASK, которые также можно объединить с любыми совместимыми флагами, описанными ранее.

Флаги FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTEи FILE_APPEND_DATADesiredAccess несовместимы с созданием или открытием файла каталога.

ObjectAttributes [in]

Указатель на структуру, OBJECT_ATTRIBUTES уже инициализированную подпрограммой InitializeObjectAttributes . Если вызывающий объект выполняется в контексте системного процесса, этот параметр может иметь значение NULL. В противном случае вызывающий объект должен задать OBJ_KERNEL_HANDLE атрибут в вызове InitializeObjectAttributes.

В эту структуру для объекта файла входят следующие элементы:

IoStatusBlock [out]

Указатель на переменную типа IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения о запрошенной операции. При возвращении из NtCreateNamedPipeFile элемент Information переменной содержит одно из следующих значений:

• FILE_CREATED
• FILE_OPENED
• FILE_OVERWRITTEN
• FILE_SUPERSEDED
• FILE_EXISTS
• FILE_DOES_NOT_EXIST

ShareAccess [in]

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

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

CreateDisposition [in]

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

CreateOptions [in]

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

NamedPipeType [in]

Тип создаваемого именованного канала (byte-type или message-type).

ReadMode [in]

Режим, в котором считывается канал (тип байта или типа сообщения).

CompletionMode [in]

Указывает, как должна быть завершена операция.

MaximumInstances [in]

Максимальное число одновременных экземпляров именованного канала.

InboundQuota [in]

Указывает квоту пула, зарезервированную для операций записи во входящую сторону именованного канала.

OutboundQuota [in]

Указывает квоту пула, зарезервированную для операций записи во входящую сторону именованного канала.

DefaultTimeout [в, необязательно]

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

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

Значение функции — это окончательное состояние операции создания или открытия.

Комментарии

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

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

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

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

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

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

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

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

Требования