PMRX_CREATE_V_NET_ROOT回调函数（mrx.h）

项目
02/07/2025

RDBSS 调用 MRxCreateVNetRoot 例程，以请求网络微型重定向程序创建V_NET_ROOT结构，在某些情况下，NET_ROOT结构。

语法

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

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

参数

Context

[in， out]指向网络微型重定向程序用来在最终完成调用时通知 RDBSS 的回调上下文的指针。这包括 Context->RxContext请求的RX_CONTEXT结构。 Context 参数包括 context->pVNetRoot构造的V_NET_ROOT结构。此V_NET_ROOT结构包含指向 pVNetRoot- >pNetRootNET_ROOT结构的指针。 NET_ROOT结构还包含指向 pNetRoot- >pSrvCall处SRV_CALL结构的指针。

返回值

RDBSS 预期 MRxCreateVNetRoot 在成功或失败时返回STATUS_PENDING。此行为会导致 RDBSS 要求异步完成此调用。网络微型重定向程序应将STATUS_SUCCESS映射到STATUS_PENDING作为 MRxCreateVNetRoot的返回值。

调用完成后，Context->VirtualNetRootStatus 和 Context->NetRootStatus 成员中返回最终完成状态，Context 结构的回调成员中的例程由网络微型重定向程序调用。这些成员最初包含STATUS_SUCCESS，直到网络微型重定向程序在完成时更改此值。如果调用成功完成，则两个成员都包含STATUS_SUCCESS。

未能创建V_NET_ROOT或NET_ROOT结构时，将返回以下VirtualNetRootStatus 或 NetRootStatus 成员的以下常见错误代码之一（尽管其他错误代码可能）：

返回代码	描述
STATUS_CONNECTION_RESET	已重置与远程资源的连接。
STATUS_IO_TIMEOUT	I/O 请求发生超时。
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结构。
正在创建与现有NET_ROOT结构关联的新V_NET_ROOT结构。

可以通过检查与NET_ROOT结构关联的上下文是否为 NULL 来区分这两种情况。

MRxCreateVNetRoot 的网络微型重定向程序实现应返回初始调用STATUS_PENDING。处理完成后，网络微型重定向程序将调用作为 Context 参数一部分传入的回调例程，以通知 RDBSS 调用已完成并返回完成状态。网络微型重定向程序应调用的回调例程被指定为作为 上下文 参数传递的MRX_CREATENETROOT_CONTEXT结构中的回调成员。 MRxCreateVNetRoot 调用的最终完成状态必须存储在 VirtualNetRootStatus 中，NetRootStatusContext 参数的成员。请注意，为NET_ROOT和V_NET_ROOT结构返回单独的状态。

在网络微型重定向器中实现 MRxCreateVNetRoot 也因传输句柄的需要而复杂。某些与传输相关的接口需要创建句柄并用于所有通信。创建NET_ROOT或V_NET_ROOT结构可能需要为网络通信建立与传输相关的句柄。由于建立网络连接的过程可能很耗时，因此建立连接后，尽可能长时间地使用连接进行通信是有意义的。建立到远程网络资源的传输句柄后，其他任意数量的应用程序请求都可以重复使用它。当用户应用程序终止时，将删除与进程关联的句柄。因此，在暂时性用户模式进程的上下文中建立传输句柄可能短期没有意义。因此，通常需要在已知进程的上下文中初始化NET_ROOT或V_NET_ROOT结构，这些进程在用于通信时不会消失。

用于在网络微型重定向器中管理此功能的一种方法是让 RDBSS 系统进程分配这些传输句柄。这会影响 MRxCreateVNetRoot 例程的执行方式。如果在 RDBSS 系统进程的上下文中发出了对 MRxCreateVNetRoot 的请求，则可以立即执行此调用，无需发布到工作队列。但是，为了避免出现问题，如果请求 MRxCreateVNetRoot 来自任何其他进程，则请求将使用 RxDispatchToWorkerThread 发布到系统工作队列，以便稍后执行。 RDBSS 稍后将使用其中一个系统线程来处理工作队列请求并执行 MRxCreateVNetRoot。这可确保系统进程拥有任何传输句柄。

网络微型重定向程序可以通过调用 RxGetRDBSSProcess直接从 RDBSS 接收对 MRxCreateVNetRoot 的调用。 RxGetRDBSSProcess 返回 RDBBS 进程，此值可与通过 调用 ioGetCurrentProcess返回的当前进程进行比较。如果在 RDBSS 系统进程的上下文中未启动对 MRxCreateVNetRoot 的调用，则 MRxCreateVNetRoot 可以返回STATUS_PENDING，并使用 RxDispatchToWorkerThread 向工作队列发出调用，以供 RDBSS 稍后执行。通常，这些调用将发布到 DelayedWorkQueue。

由网络微型重定向程序决定如何实现 MRxCreateVNetRoot 。如果此过程可能需要相当长的时间，则应异步完成此调用。如果需要传输句柄，则网络微型重定向程序可能需要一个长期存在的系统进程来建立这些句柄。

如果无法建立连接，则网络微型重定向程序可以尝试将NET_ROOT和V_NET_ROOT结构转换为断开连接模式（如果支持此模式），并脱机建立连接。

MRxCreateVNetRoot 完成后，应使用从网络微型重定向程序更新的相应NET_ROOT和V_NET_ROOT结构信息修改 上下文 参数。