PMRX_CREATE_SRVCALL回调函数 (mrx.h)

项目
02/26/2024

RDBSS 调用 MRxCreateSrvCall 例程，请求网络微型重定向程序创建SRV_CALL结构并与服务器建立连接。

语法

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

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

参数

SrvCall

[in， out]指向要创建的SRV_CALL结构的指针。

SrvCallCallBackContext

[in， out]指向网络微型重定向程序用于在 MRxCreateSrvCall 请求最终完成时通知 RDBSS 的回调上下文的指针。 SrvCallCallBackContext 参数指向包含此请求RX_CONTEXT结构的MRX_SRVCALLDOWN_STRUCTURE结构，以及最终完成 MRxCreateSrvCall 请求时微型重定向程序调用的 Callback 例程。

返回值

RDBSS 要求 MRxCreateSrvCall 在成功或失败时返回STATUS_PENDING。之所以出现此行为，是因为 RDBSS 要求以异步方式完成此调用。网络微型重定向程序应将STATUS_SUCCESS映射到STATUS_PENDING作为 MRxCreateSrvCall 的返回值。

调用完成后，最终完成状态将在 SrvCallCallBackContext-Status> 成员中返回，并且网络微型重定向程序调用MRX_SRVCALLDOWN_STRUCTURE结构中的 Callback 成员中的例程。此成员最初包含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 调用已完成并返回完成状态。网络微型重定向程序调用的回调例程指定为 SrvCallCallBackContext 参数MRX_SRVCALLDOWN_STRUCTURE中的 Callback 成员。调用的最终完成状态必须存储在 SrvCallCallBackContext 参数的 Status 成员中。

成功后，网络微型重定向程序还必须在 SrvCallCallBackContext 的 RecommunicateContext 成员中存储一些值。 存储在 RecommunicateContext 成员中的值是如果 MRxCreateSrvCall 成功，RDBSS 将传递给 RecommunicateContext 参数中的 MRxSrvCallWinnerNotify 的值。网络微型重定向程序还必须为创建的 SRV_CALL 结构填充 SrvCall 参数中的相应数据。请注意，传递给 MRxCreateSrvCall 的 SrvCall 参数与 SrvCallBackContext 参数MRX_SRVCALLDOWN_STRUCTURE中的 SrvCall 成员相同。此同一 SrvCall 参数也会传递到 SrvCall 参数中的 MRxSrvCallWinnerNotify。

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

解决传输句柄潜在问题的一种方法是让 RDBSS 系统进程分配传输句柄。这会影响 MRxCreateSrvCall 例程的执行方式。如果向 MRxCreateSrvCall 发出的请求是在 RDBSS 系统进程的上下文中发出的，则可以立即执行此调用，而无需发布到工作队列。但是，为了避免出现问题，如果对 MRxCreateSrvCall 的请求来自任何其他进程，则会使用 RxDispatchToWorkerThread 将请求发布到系统工作队列，供以后执行。 RDBSS 稍后将使用其系统线程之一来处理工作队列请求并执行 MRxCreateSrvCall。这可确保任何传输句柄都归系统进程所有。

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

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

此调用完成后，应使用从网络微型重定向器更新的SRV_CALL结构信息修改 SrvCall 参数。

指示支持作为 UNC 提供程序的网络微型重定向程序将从多个 UNC 提供程序 (MUP) 接收前缀声明，作为对 MRxCreateSrvCall 的调用。有关 UNC 命名和 MUP 的详细信息，请参阅对 UNC 命名和 MUP 的支持。