Функция RxRegisterMinirdr (mrx.h)

Статья
08/07/2023

RxRegisterMinirdr вызывается драйвером сетевого мини-перенаправления для регистрации драйвера в RDBSS, который добавляет сведения о регистрации во внутреннюю таблицу регистрации. RDBSS также создает объект устройства для мини-перенаправления сети.

Синтаксис

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

Параметры

[out] DeviceObject

Указатель на место хранения созданного объекта устройства.

[in, out] DriverObject

Указатель на объект драйвера сетевого мини-перенаправления. Каждый драйвер получает указатель на объект драйвера в параметре своей подпрограммы DriverEntry . Этот объект драйвера будет использоваться для создания объекта устройства для драйвера сетевого мини-перенаправления.

[in] MrdrDispatch

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

[in] Controls

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

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

Если этот флаг установлен, он указывает, что мини-перенаправление сети не поддерживает UNC-имена.

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

Если этот флаг установлен, он указывает, что мини-перенаправление сети не поддерживает почтовые слои.

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

Если этот флаг установлен, он указывает, что сетевой мини-перенаправление не хочет, чтобы RDBSS инициализировал точки входа диспетчера драйвера мини-перенаправления, чтобы они указывали на внутренние подпрограммы RDBSS. Этот параметр будет использоваться только в необычных обстоятельствах. Обычно RDBSS устанавливает точки входа диспетчеризации драйвера и быструю отправку ввода-вывода в объекте драйвера сетевого мини-перенаправления, чтобы указывать на подпрограммы, внутренние для RDBSS.

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

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

[in] DeviceName

Указатель на буфер, содержащий строку Юникода с нулем, которая называет объект устройства. Строка должна быть полным именем пути. Этот параметр передается как DeviceName подпрограмме IoCreateDevice с помощью RDBSS.

[in] DeviceExtensionSize

Размер, заданный драйвером мини-перенаправления для количества байтов, выделяемых для расширения устройства объекта устройства. Внутренняя структура расширения устройства определяется драйвером. Этот параметр добавляется к размеру расширения устройства, используемого RDBSS, и передается в качестве параметра DeviceExtensionSize подпрограмме IoCreateDevice с помощью RDBSS.

[in] DeviceType

Тип устройства, используемый при создании объекта устройства. Указывает одну из системных констант FILE_DEVICE_XXX, указывающих тип устройства или определенное поставщиком значение для нового типа устройства. Обычно это значение будет FILE_DEVICE_NETWORK_FILE_SYSTEM для драйверов мини-перенаправления сети. Этот параметр передается как DeviceType в подпрограмму IoCreateDevice с помощью RDBSS.

[in] DeviceCharacteristics

Характеристики устройства, используемые при создании объекта устройства. Он указывает одну или несколько системных констант, объединенных вместе, которые предоставляют дополнительные сведения об устройстве драйвера. Это значение должно включать FILE_REMOTE_DEVICE для драйверов мини-перенаправления сети, но это может сочетаться с другими характеристиками, такими как FILE_DEVICE_SECURE_OPEN. Этот параметр передается как DeviceCharacteristics в подпрограмму IoCreateDevice с помощью RDBSS.

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

RxRegisterMinirdr возвращает STATUS_SUCCESS об успешном выполнении или одно из следующих значений ошибки при сбое:

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для создания объекта устройства.
STATUS_INVALID_PARAMETER	В подпрограмму передан недопустимый параметр. Эта ошибка будет возвращена, если параметр DeviceObject является указателем NULL .
STATUS_OBJECT_NAME_COLLISION	При попытке создать этот объект устройства произошло столкновение имен.
STATUS_OBJECT_NAME_EXISTS	Объект устройства с таким именем уже существует.
STATUS_UNSUCCESSFUL	Вызов для создания объекта устройства вернул объект устройства NULL .

Сетевой мини-перенаправитель регистрируется в RDBSS всякий раз, когда драйвер загружается ядром, и отменяет регистрацию в RDBSS при выгрузке драйвера. Не монолитный драйвер (мини-перенаправитель сети SMB) взаимодействует с Rdbss.sys, другим драйвером ядра. Для монолитного драйвера мини-перенаправления сети, который статически связывается с Rdbsslib.lib, это просто вызов подпрограммы библиотеки Rdbsslib.lib .

Сетевой мини-перенаправитель сообщает RDBSS о том, что он был загружен, вызвав RxRegisterMinirdr, подпрограмму регистрации, экспортированную из RDBSS. При первом запуске драйвера сетевого мини-перенаправления (в его подпрограмме DriverEntry ) драйвер вызывает подпрограмму RDBSS RxRegisterMinirdr , чтобы зарегистрировать драйвер сетевого мини-перенаправления в RDBSS. На основе параметров, переданных в RxRegisterMinirdr, RDBSS вызывает IoCreateDevice , чтобы создать объект устройства для драйвера сетевого мини-перенаправления.

В рамках этого процесса регистрации мини-перенаправитель сети передает параметр в RxRegisterMinirdr , который является указателем на большую структуру, MINIRDR_DISPATCH, которая содержит сведения о конфигурации для мини-перенаправления сети и таблицу отправки указателей на подпрограммы обратного вызова, реализованные драйвером сетевого мини-перенаправления. Эти данные конфигурации используются для настройки внутренних таблиц RDBSS для использования с этим мини-перенаправлением сети. RDBSS использует процедуры обратного вызова, переданные в этой структуре, для взаимодействия с мини-перенаправлением сети. Сетевой мини-перенаправитель может реализовать только некоторые из этих процедур обратного вызова. Для любой не реализованной процедуры обратного вызова в таблице диспетчеризации, передаваемой в RDBSS, следует задать указатель NULL . RDBSS будет вызывать только подпрограммы обратного вызова, реализованные мини-перенаправлением сети.

Обратите внимание, что подпрограмма RxRegisterMinirdr задает все подпрограммы диспетчера драйвера сетевого мини-перенаправления, указывая на подпрограмму диспетчера RDBSS верхнего уровня RxFsdDispatch. Сетевой мини-перенаправитель может переопределить это поведение, сохранив копию точек входа диспетчеризации драйвера, вызвав RxRegisterMinirdr и перезаписав отправку драйвера с собственными точками входа после вызова RxRegisterMinirdr . Сетевой мини-перенаправитель также может предотвратить копирование подпрограммы диспетчеризации драйвера подпрограммой RxRegisterMinirdr , если бит RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH задан в параметре Controls .

Если вызов RxRegisterMinirdr выполнен успешно, инициализируется ряд элементов в RDBSS_DEVICE_OBJECT, на которые указывает параметр DeviceObject , включая следующие:

Элемент Dispatch имеет значение параметра MrdrDispatch .
Для элемента RegistrationControls задается параметр Controls .
Для элемента DeviceName задан параметр DeviceName .
Член RegisterUncProvider имеет значение TRUE , если бит RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS в параметре Controls не задан.
Член RegisterMailSlotProvider имеет значение TRUE , если бит RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS в параметре Controls не задан.
Член NetworkProviderPriority имеет приоритет поставщика сети, который будет использовать MUP.

Если вызов RxRegisterMinirdr выполнен успешно, а бит RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER в параметре Controls не задан, инициализируется ряд других элементов в RDBSS_DEVICE_OBJECT, на которые указывает параметр DeviceObject , в том числе следующие:

Структура элемента pRxNetNameTable инициализируется.
Элемент RxNetNameTableInDeviceObject.IsNetNameTable имеет значение TRUE.
Структура элемента pRdbssScavenger инициализируется.

Если вызов RxRegisterMinirdr выполнен успешно, RDBSS устанавливает внутреннее состояние мини-перенаправления сети в RDBSS на RDBSS_STARTABLE.

Сетевой мини-перенаправитель фактически не запускает операцию, пока не получит вызов к своей подпрограмме MRxStart , одной из подпрограмм обратного вызова, переданных в MINIRDR_DISPATCH структуре. Подпрограмма обратного вызова MrxStart должна быть реализована драйвером сетевого мини-перенаправления, если он хочет получать обратные вызовы для операций, если мини-перенаправитель сети не сохраняет собственные точки входа диспетчеризации драйвера. В противном случае RDBSS разрешит драйверу только следующие пакеты запросов ввода-вывода, пока MrxStart не вернет успешно:

Запросы IRP для операций создания устройств и операций устройства, где параметр FileObject->FileName.Length в IRPSP равен нулю, а параметр FileObject->RelatedFileObject имеет значение NULL.

Для любого другого запроса IRP подпрограмма диспетчеризации RDBSS RxFsdDispatch вернет состояние STATUS_REDIRECTOR_NOT_STARTED.

Подпрограмма диспетчеризации RDBSS также завершит сбой всех запросов для следующих пакетов запросов ввода-вывода:

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

Подпрограмма MrxStart для мини-перенаправления сети вызывается RDBSS при вызове подпрограммы RxStartMiniRdr . RDBSS RxStartMinirdr обычно вызывается в результате запроса FSCTL или IOCTL от приложения или службы пользовательского режима для запуска мини-перенаправления сети. Вызов RxStartMinirdr не может быть выполнен из процедуры DriverEntry мини-перенаправителя сети после успешного вызова RxRegisterMinirdr , так как для некоторых процессов запуска требуется завершить инициализацию драйвера. После получения вызова RxStartMinirdr RDBSS завершает процесс запуска, вызывая подпрограмму MrxStart мини-перенаправителя сети. Если вызов MrxStart возвращает успешное выполнение, RDBSS устанавливает внутреннее состояние мини-перенаправления в RDBSS на RDBSS_STARTED.

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	mrx.h (включая Mrx.h)
IRQL	<= APC_LEVEL