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

Статья
10/13/2023

Подпрограмма MRxCreateSrvCall вызывается RDBSS , чтобы запросить, чтобы сетевой мини-перенаправитель создавал структуру SRV_CALL и устанавливал соединение с сервером.

Синтаксис

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

NTSTATUS PmrxCreateSrvcall(
  IN OUT PMRX_SRV_CALL SrvCall,
  IN OUT PMRX_SRVCALL_CALLBACK_CONTEXT SrvCallCallBackContext
)
{...}

Параметры

SrvCall

[вход, выход] Указатель на структуру SRV_CALL, которую необходимо создать.

SrvCallCallBackContext

[вход, выход] Указатель на контекст обратного вызова, используемый мини-перенаправлением сети для уведомления RDBSS о завершении запроса MRxCreateSrvCall . Параметр SrvCallCallBackContext указывает на MRX_SRVCALLDOWN_STRUCTURE структуру, которая содержит структуру RX_CONTEXT для этого запроса, а также подпрограмму обратного вызова , которую мини-перенаправление вызывает при завершении запроса MRxCreateSrvCall .

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

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

Окончательное состояние завершения возвращается в члене SrvCallBackContext-Status> после завершения вызова, а подпрограмма в члене Callback в структуре MRX_SRVCALLDOWN_STRUCTURE вызывается сетевым мини-перенаправлением. Изначально этот элемент содержит STATUS_BAD_NETWORK_PATH до тех пор, пока мини-перенаправитель сети не изменит это значение после завершения.

Член SrvCallCallBackContext-Status> содержит STATUS_SUCCESS об успешном выполнении вызова или один из следующих распространенных кодов ошибок при сбое (хотя возможны и другие коды ошибок):

Код возврата	Описание
STATUS_BAD_NETWORK_PATH	Указан недопустимый сетевой путь.
STATUS_NETWORK_UNREACHABLE	Сеть была недоступна.

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

Создание структуры SRV_CALL обычно включает по крайней мере один круговой путь сети. Эта операция может занять значительное время, так как может потребоваться установить сетевое подключение с удаленным ресурсом. Чтобы обеспечить продолжение асинхронных операций, создание структуры SRV_CALL моделиируется как двухэтапное действие. Каждый вызов мини-перенаправления сети для создания структуры SRV_CALL сопровождается вызовом от сетевого мини-перенаправления к RDBSS, который указывает состояние завершения запроса. RDBSS предполагает, что MRxCreateSrvCall будет завершен асинхронно. Поэтому RDBSS ожидает , что MRxCreateSrvCall вернет STATUS_PENDING. RDBSS будет получать уведомления с помощью процедуры обратного вызова после завершения вызова.

Ожидается, что реализация сетевого мини-перенаправителя MRxCreateSrvCall вернет STATUS_PENDING в начальный вызов. После завершения обработки сетевой мини-перенаправитель вызывает подпрограмму обратного вызова, передаваемую как часть параметра SrvCallCallBackContext , чтобы уведомить RDBSS о завершении вызова и вернуть состояние завершения. Подпрограмма обратного вызова, вызываемая сетевым мини-перенаправителем, указывается в качестве элемента Callback в MRX_SRVCALLDOWN_STRUCTURE параметра SrvCallCallBackContext . Окончательное состояние завершения вызова должно храниться в элементе Status параметра SrvCallCallBackContext .

При успешном выполнении сетевой мини-перенаправитель также должен хранить некоторое значение в элементе RecommunicateContextSrvCallCallBackContext. Значение, хранящееся в элементе RecommunicateContext , — это значение, которое RDBSS будет передавать в MRxSrvCallWinnerNotify в параметре RecommunicateContext , если MRxCreateSrvCall был успешно выполнен. Сетевой мини-перенаправитель также должен заполнить соответствующие данные в параметре SrvCall для созданной структуры SRV_CALL. Обратите внимание, что параметр SrvCall , передаваемый в MRxCreateSrvCall , совпадает с параметром SrvCall в MRX_SRVCALLDOWN_STRUCTURE параметра SrvCallBackContext . Этот же параметр SrvCall также передается в MRxSrvCallWinnerNotify в параметре SrvCall .

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

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

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

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

После завершения этого вызова параметр SrvCall должен быть изменен с помощью сведений о структуре SRV_CALL, обновленных из сетевого мини-перенаправления.

Сетевой мини-перенаправитель, указывающий на поддержку в качестве поставщика UNC, получит утверждение префикса от поставщика MUP в качестве вызова MRxCreateSrvCall. Дополнительные сведения об именовании UNC и MUP см. в разделе Поддержка именования UNC и MUP.