функция обратного вызова PMRX_CREATE_V_NET_ROOT (mrx.h)

Статья
10/13/2023

Подпрограмма MRxCreateVNetRoot вызывается RDBSS для запроса на создание мини-перенаправителя сети структуры V_NET_ROOT и, в некоторых случаях, структуры NET_ROOT.

Синтаксис

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

NTSTATUS PmrxCreateVNetRoot(
  IN OUT PMRX_CREATENETROOT_CONTEXT Context
)
{...}

Параметры

Context

[вход, выход] Указатель на контекст обратного вызова, используемый мини-перенаправителем сети для уведомления RDBSS о завершении вызова. Сюда входит RX_CONTEXT структура запроса в Context-RxContext>. Параметр Context включает V_NET_ROOT структуру, которая будет создана в Context-pVNetRoot>. Эта V_NET_ROOT структура содержит указатель на структуру NET_ROOT в pVNetRoot-pNetRoot>. Структура NET_ROOT также содержит указатель на структуру SRV_CALL в pNetRoot-pSrvCall>.

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

RDBSS ожидает, что MRxCreateVNetRoot возвращает STATUS_PENDING об успешном или неудачном выполнении. Такое поведение возникает, так как RDBSS ожидает, что этот вызов будет выполнен асинхронно. Мини-перенаправление сети должно сопоставлять STATUS_SUCCESS с STATUS_PENDING в качестве возвращаемого значения для MRxCreateVNetRoot.

Окончательное состояние завершения возвращается в элементах Context-VirtualNetRootStatus> и Context-NetRootStatus> после завершения вызова, а подпрограмма в элементе обратного вызова структуры Контекст вызывается мини-перенаправлением сети. Эти элементы изначально содержат STATUS_SUCCESS до тех пор, пока мини-перенаправление сети не изменит это значение по завершении. Если вызов выполнен успешно, оба элемента содержат STATUS_SUCCESS.

При сбое при создании структуры V_NET_ROOT или NET_ROOT возвращается один из следующих распространенных кодов ошибок для элементаVirtualNetRootStatus или NetRootStatus (хотя возможны и другие коды ошибок):

Код возврата	Описание
STATUS_CONNECTION_RESET	Подключение к удаленному ресурсу было сброшено.
STATUS_IO_TIMEOUT	Истекло время ожидания для запроса ввода-вывода.
STATUS_RETRY	Удаленный загрузочный сервер не был готов к выполнению запроса.
STATUS_UNEXPECTED_NETWORK_ERROR	Произошла непредвиденная сетевая ошибка, вызванная недопустимым дескриптором.

Две важные абстракции, используемые в интерфейсе между RDBSS и мини-перенаправлением сети, — это структура SRV_CALL и структура NET_ROOT/V_NET_ROOT. Структура SRV_CALL соответствует контексту, связанному с сервером, с которым установлено соединение. Структура NET_ROOT соответствует общей папке на сервере. Структура V_NET_ROOT может рассматриваться как часть пространства имен под структурой NET_ROOT, на которую претендует мини-перенаправитель сети.

Создание структуры NET_ROOT/V_NET_ROOT обычно включает по крайней мере один круговой путь сети. Выполнение этой операции может занять значительное время, так как может потребоваться установить сетевое подключение к удаленному ресурсу. Чтобы обеспечить продолжение асинхронных операций, создание структуры NET_ROOT/V_NET_ROOT моделиируется как двухфазное действие. За каждым вызовом мини-перенаправления сети для создания структуры NET_ROOT/V_NET_ROOT следует обратный вызов от мини-перенаправителя сети к RDBSS, который указывает RDBSS о состоянии завершения запроса к мини-перенаправлению сети. Так как RDBSS ожидает, что MRxCreateVNetRoot завершается асинхронно, RDBSS ожидает, что MRxCreateVNetRoot вернет STATUS_PENDING. После завершения вызова RDBSS будет получать уведомления с помощью процедуры обратного вызова.

MRxCreateVNetRoot должен иметь дело с двумя интересующими случаями:

Создается новая структура V_NET_ROOT и связанная с ней новая структура NET_ROOT.
Создается новая структура V_NET_ROOT, связанная с существующей структурой NET_ROOT.

Эти два варианта можно различать, проверяя, имеет ли контекст, связанный со структурой NET_ROOT, значение NULL.

Ожидается, что реализация сетевого мини-перенаправления MRxCreateVNetRoot вернет STATUS_PENDING к первоначальному вызову. После завершения обработки мини-перенаправитель сети вызывает подпрограмму обратного вызова, переданную в качестве части параметра Context , чтобы уведомить RDBSS о том, что вызов завершен, и возвратить состояние завершения. Подпрограмма обратного вызова, которую должен вызывать мини-перенаправитель сети, указана в качестве члена обратного вызова в структуре MRX_CREATENETROOT_CONTEXT, переданной в качестве параметра Context . Окончательное состояние завершения вызова MRxCreateVNetRoot должно храниться в элементах VirtualNetRootStatus и NetRootStatus параметра Context . Обратите внимание, что для структур NET_ROOT и V_NET_ROOT возвращается отдельное состояние.

Реализация MRxCreateVNetRoot в сетевом мини-перенаправлении также осложняется потребностью в дескрипторах транспорта. Для некоторых интерфейсов, связанных с транспортом, требуется создать и использовать дескриптор для всего обмена данными. Создание структуры NET_ROOT или V_NET_ROOT может потребовать установки связанных с транспортировкой дескрипторов для сетевого взаимодействия. Так как процесс установки сетевого подключения может занять много времени, после установки соединения имеет смысл использовать его для обмена данными как можно дольше. После установки дескриптора транспорта к удаленному сетевому ресурсу его можно повторно использовать любым количеством других запросов приложений. При завершении работы пользовательского приложения дескрипторы, связанные с процессом, удаляются. По этой причине установка дескрипторов транспорта в контексте временного процесса в пользовательском режиме, который может быть кратковременным, не имеет смысла. Поэтому структура NET_ROOT или V_NET_ROOT обычно должна быть инициализирована в контексте хорошо известного процесса, который не исчезнет, пока эти дескрипторы транспорта используются для обмена данными.

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

Сетевой мини-перенаправитель может определить, был ли получен вызов MRxCreateVNetRoot непосредственно из RDBSS, вызвав RxGetRDBSSProcess. RxGetRDBSSProcess возвращает процесс RDBBS, и это значение можно сравнить с текущим процессом, возвращенным путем вызова IoGetCurrentProcess. Если вызов MRxCreateVNetRoot не был инициирован в контексте системного процесса RDBSS, то MRxCreateVNetRoot может вернуть STATUS_PENDING и отправить вызов в рабочую очередь с помощью RxDispatchToWorkerThread для последующего выполнения RDBSS. Как правило, эти вызовы будут отправляться в DelayedWorkQueue.

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

Если установить подключение невозможно, мини-перенаправитель сети может попытаться перевести NET_ROOT и V_NET_ROOT структуры в отключенный режим (если это поддерживается) и установить подключение в автономном режиме.

После завершения MRxCreateVNetRoot параметр Context должен быть изменен соответствующим NET_ROOT и V_NET_ROOT сведения о структуре, которые обновляются из мини-перенаправления сети.