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

Статья
10/11/2023

RxStartMinirdr вызывается для запуска сетевого мини-перенаправителя, который ранее вызывался для регистрации в RDBSS. В рамках RxStartMinirdr RDBSS также регистрирует драйвер сетевого мини-перенаправления в качестве поставщика универсального соглашения об именовании (UNC) с поставщиком MUP, если драйвер указывает на поддержку UNC-имен.

Синтаксис

NTSTATUS RxStartMinirdr(
  [in]  IN PRX_CONTEXT RxContext,
  [out] OUT PBOOLEAN   PostToFsp
);

Параметры

[in] RxContext

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

[out] PostToFsp

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

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

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

Код возврата	Описание
STATUS_ACCESS_DENIED	Сбой запроса на регистрацию в качестве поставщика UNC из-за отказа в доступе.
STATUS_ACCESS_VIOLATION	Запрос на регистрацию в качестве поставщика UNC завершился сбоем из-за нарушения доступа.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для выполнения этой процедуры.
STATUS_PENDING	Последовательность запуска для RDBSS и сетевых мини-перенаправлений должна быть завершена в контексте системного процесса, а не процесса приложения в пользовательском режиме. Если вызов RxStartMinirdr поступает из процесса пользовательского режима (например, запроса на обслуживание в пользовательском режиме), запрос отправляется для последующей обработки в RDBSS и возвращается STATUS_PENDING. Эта ошибка также может быть возвращена, если определенные внутренние блокировки RDBSS не могут быть получены без ожидания. Вызов будет выполнен позже из системного потока.
STATUS_REDIRECTOR_STARTED	Сетевой мини-перенаправление уже запущен.

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

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

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

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

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

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

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

Когда RDBSS получает запрос FSCTL или IOCTL, отправленный драйверу сетевого мини-перенаправления из пользовательского режима, RDBSS создает структуру RX_CONTEXT и передает этот вызов в процедуру обратного вызова MRxLowIOSubmit[LOWIO_OP_FSCTL] сетевого мини-перенаправления или MRxLowIOSubmit[LOWIO_OP_IOCTL] , определенную в структуре MINIRDR_DISPATCH. Реализация этой подпрограммы обратного вызова сетевого мини-перенаправления распознает запрос на запуск и вызов RxStartMinirdr. Этот обычный процесс событий приведен ниже более подробно:

Приложение в пользовательском режиме отправляет частный запрос FSCTL или IOCTL для запуска сетевого мини-перенаправителя.
Драйвер ядра RDBSS получает запрос FSCTL или IOCTL от имени сетевого мини-перенаправителя, так как RDBSS заменил точки входа диспетчера драйвера мини-перенаправления, чтобы указать на внутренние подпрограммы RDBSS. Обратите внимание, что при этом предполагается, что сетевой мини-перенаправитель не задал RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH в параметре Controls при вызове RxRegisterMinirdr. Этот параметр, передаваемый в RxRegisterMinirdr , является необычным и указывает, что сетевой мини-перенаправитель не хочет, чтобы RDBSS заменял точки входа диспетчера драйвера.
RDBSS получает запрос FSCTL или IOCTL внутренне от имени перенаправителя сети. Диспетчер RDBSS выделяет и инициализирует структуру RX_CONTEXT. Затем RDBSS вызывает подпрограмму сетевого мини-перенаправления MRxLowIOSubmit[LOW_OP_FSCTL] или MRxLowIOSubmit[LOW_OP_IOCTL] , определенную в структуре MINIRDR_DISPATCH для этого сетевого мини-перенаправления, передавая инициализированную структуру RX_CONTEXT в качестве параметра.
Реализация сетевого мини-перенаправления этой подпрограммы обратного вызова распознает частный запрос FSCTL или IOCTL для запуска и вызова RxStartMinirdr, передавая указатель структуры RX_CONTEXT, полученной от RDBSS в качестве параметра RxContext , и адрес члена PostToFSPRxContext в качестве параметра PostToFsp .
Так как этот вызов был инициирован из пользовательского режима, RxStartMinirdr возвращает STATUS_PENDING и устанавливает для PostToFsp значение TRUE.
Подпрограмма сетевого мини-перенаправления MRxLowIOSubmit[LOW_OP_FSCTL] или MRxLowIOSubmit[LOW_OP_IOCTL] получит это возвращаемое значение и передает его обратно диспетчеру RDBSS.
Диспетчер RDBSS получит STATUS_PENDING возвращаемое значение и присвоит PostToFsp значение TRUE, а затем отправляет запрос в рабочий поток для повторного выполнения вызова сетевого мини-перенаправителя.

После этого есть два возможных результата в зависимости от того, был ли запрошен FSCTL или IOCTL как асинхронная или синхронная операция.

Если бы это был асинхронный запрос, произошло бы следующее:

Вызывающий объект пользовательского режима получит ответ STATUS_PENDING от вызова. В конечном итоге опубликованный рабочий поток вызовет RxStartMinirdr из потока файловой системы, и вызов будет обработан. Подпрограмма RxStartMinirdr попытается зарегистрировать сетевой мини-перенаправитель в качестве поставщика UNC, если потребуется. В версиях Windows, предшествующих Windows Vista, RDBSS попытается зарегистрировать мини-перенаправление сети в качестве файловой системы в диспетчере ввода-вывода. Если эти вызовы выполняются успешно, RxStartMinirdr вызывает подпрограмму обратного вызова MrxStart , реализованную сетевым мини-перенаправлением. Возвращаемое значение из MrxStart в конечном итоге будет возвращено приложению пользовательского режима, которое инициировало процесс последовательности вызова в качестве асинхронной операции.

Если бы это был синхронный запрос, произошло бы следующее:

Вызывающий объект пользовательского режима не получит ответ STATUS_PENDING, но будет вынужден ждать, пока вызов не будет возвращен из размещенного рабочего потока. В конечном итоге опубликованный рабочий поток вызовет RxStartMinirdr из потока файловой системы, и вызов будет обработан. Подпрограмма RxStartMinirdr попытается зарегистрировать сетевой мини-перенаправитель в качестве поставщика UNC, если потребуется. В версиях Windows, предшествующих Windows Vista, RDBSS попытается зарегистрировать мини-перенаправление сети в качестве файловой системы в диспетчере ввода-вывода. Если эти вызовы выполняются успешно, RxStartMinirdr вызывает подпрограмму обратного вызова MrxStart , реализованную сетевым мини-перенаправлением. Возвращаемое значение из MrxStart будет возвращено приложению пользовательского режима, которое инициировало процесс последовательности вызовов.

Если сетевой мини-перенаправление указывает на поддержку UNC при регистрации в RDBSS (параметр Controls для RxRegisterMinirdr), RxStartMinirdr попытается зарегистрировать параметр DeviceName сетевого мини-перенаправления в качестве поставщика UNC с MUP (RDBSS вызывает FsRtlRegisterUncProvider от имени сетевого мини-перенаправления).

В версиях Windows до Windows Vista RxStartMinirdr регистрирует файловую систему в диспетчере ввода-вывода (RDBSS вызывает IoRegisterFileSystem от имени сетевого мини-перенаправителя).

Если вызовы выполнены успешно, RxStartMinirdr вызывает подпрограмму MrxStart сетевого мини-перенаправления. Если MrxStart возвращает успешное выполнение, внутреннее состояние мини-перенаправления в RDBSS устанавливается в RDBSS_STARTED. Элемент StartStopContext.Version объекта устройства мини-перенаправления также увеличивается.

Последовательность запуска для RDBSS и сетевого мини-перенаправителя должна быть завершена в контексте системного процесса, если запрашивается асинхронная операция. Если вызов RxStartMinirdr поступает из процесса в пользовательском режиме (например, запроса на обслуживание в пользовательском режиме), запрос будет внутренне размещен RDBSS в рабочей очереди для последующей обработки и будет возвращен STATUS_PENDING, а параметр PostToFsp будет иметь значение TRUE. Кроме того, если определенные внутренние блокировки RDBSS не могут быть получены без ожидания, возвращается STATUS_PENDING, а postToFsp имеет значение TRUE. Когда возвращается STATUS_PENDING, RxStartMinirdr будет вызываться снова из системного процесса. Если запрос FSCTL или IOCTL, который инициировал вызов RxStartMinirdr , был задан для асинхронной операции, RDBSS вернет STATUS_PENDING резервной копии цепочки вызовов в исходный запрос FSCTL или IOCTL из пользовательского режима. В отличие от этого, если запрос FSCTL или IOCTL был для синхронной операции, вызов также будет отправляться в рабочий поток для последующего выполнения, но вызов FSCTL или IOCTL не вернется в пользовательский режим, пока RxStartMinirdr не будет выполнен в контексте процесса файловой системы. В этом случае вызывающий объект FSCTL или IOCTL никогда не увидит возврата ошибки STATUS_PENDING. Более типичным поведением является запуск синхронного запроса для этих операций запуска и остановки, чтобы упростить код приложения в пользовательском режиме.

При ненормальном завершении или другом сбое RxStartMinirdr попытается отменить эти операции, включая отмену регистрации поставщика UNC с помощью MUP, отмену регистрации файловой системы, освобождение памяти, выделенной для хранения доменного имени, которое будет использоваться широковещательными передачами mailslot, и обновление внутренних таблиц RDBSS.

Требования

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