функция обратного вызова 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

[in, out] Указатель на контекст обратного вызова, используемый мини-перенаправлением сети, чтобы уведомить RDBSS о завершении вызова. Сюда входит структура RX_CONTEXT запроса по Context->RxContext. Параметр контекста включает структуру 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.

Окончательное состояние завершения возвращается в контексте —>VirtualNetRootStatus и контексте контекста>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 ожидает, что MRxCreateVNetRoot выполняется асинхронно, RDBSS ожидает, что MRxCreateVNetRoot возвращать STATUS_PENDING. RDBSS будет уведомляться с помощью подпрограммы обратного вызова после завершения вызова.

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

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

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

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

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

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

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

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

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

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