PMRX_CREATE_SRVCALL función de devolución de llamada (mrx.h)

Artículo
10/13/2023

RDBSS llama a la rutina MRxCreateSrvCall para solicitar que el minidirector de red cree una estructura de SRV_CALL y establezca la conexión con un servidor.

Sintaxis

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

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

Parámetros

SrvCall

[in, out] Puntero a la estructura SRV_CALL que se va a crear.

SrvCallCallBackContext

[in, out] Puntero al contexto de devolución de llamada usado por el minidirector de red para notificar a RDBSS cuando se complete la solicitud MRxCreateSrvCall . El parámetro SrvCallBackBackContext apunta a una estructura de MRX_SRVCALLDOWN_STRUCTURE que contiene la estructura de RX_CONTEXT para esta solicitud, así como la rutina de devolución de llamada a la que el minidirector llama cuando la solicitud MRxCreateSrvCall se completa finalmente.

Valor devuelto

RDBSS espera que MRxCreateSrvCall devuelva STATUS_PENDING en caso de éxito o error. Este comportamiento resulta porque RDBSS espera que esta llamada se complete de forma asincrónica. Un minidirector de red debe asignar STATUS_SUCCESS a STATUS_PENDING como valor devuelto para MRxCreateSrvCall.

El estado de finalización final se devuelve en el miembro SrvCallCallBackContext-Status> una vez completada la llamada y la rutina del miembro Callback de la estructura MRX_SRVCALLDOWN_STRUCTURE llama al minidirector de red. Este miembro contiene inicialmente STATUS_BAD_NETWORK_PATH hasta que el minidirector de red cambia este valor al finalizar.

El miembro SrvCallCallBackContext-Status> contiene STATUS_SUCCESS si la llamada se completa correctamente o uno de los siguientes códigos de error comunes en caso de error (aunque son posibles otros códigos de error):

Código devuelto	Descripción
STATUS_BAD_NETWORK_PATH	La ruta de acceso de red que se especificó es incorrecta.
STATUS_NETWORK_UNREACHABLE	No se pudo acceder a la red.

Comentarios

Las dos abstracciones importantes usadas en la interfaz entre RDBSS y un minidirector de red son la estructura SRV_CALL y la estructura NET_ROOT. Una estructura de SRV_CALL corresponde al contexto asociado a un servidor una vez establecida una conexión. Una estructura de NET_ROOT corresponde a un recurso compartido en un servidor (esto también se puede ver como una parte del espacio de nombres que ha reclamado un minidirector de red).

La creación de una estructura de SRV_CALL normalmente implica al menos un recorrido de ida y vuelta de red. Esta operación puede tardar mucho tiempo en completarse porque es posible que sea necesario establecer una conexión de red con un recurso remoto. Para asegurarse de que las operaciones asincrónicas continúan, la creación de una estructura de SRV_CALL se modela como una actividad en dos fases. Cada llamada a un minidirector de red para crear una estructura de SRV_CALL va acompañada de una llamada desde el minidirector de red a RDBSS que especifica el estado de finalización de la solicitud. RDBSS supone que MRxCreateSrvCall se completará de forma asincrónica. Por lo tanto, RDBSS espera que MRxCreateSrvCall devuelva STATUS_PENDING. Se notificará a RDBSS mediante la rutina de devolución de llamada cuando finalice la llamada.

Se espera que una implementación de minidirector de red de MRxCreateSrvCall devuelva STATUS_PENDING a la llamada inicial. Cuando se completa el procesamiento, el minidirector de red llama a la rutina de devolución de llamada que se pasa como parte del parámetro SrvCallCallBackContext para notificar a RDBSS que la llamada se completó y para devolver el estado de finalización. La rutina de devolución de llamada a la que llama el minidirector de red se especifica como miembro callback en el MRX_SRVCALLDOWN_STRUCTURE del parámetro SrvCallBackBackContext . El estado de finalización final de la llamada debe almacenarse en el miembro Status del parámetro SrvCallBackContext .

Si se ejecuta correctamente, el minidirector de red también debe almacenar algún valor en el miembro RecommunicateContext del SrvCallCallBackContext. El valor almacenado en el miembro RecommunicateContext es el valor que RDBSS pasará a MRxSrvCallWinnerNotify en el parámetro RecommunicateContext si MRxCreateSrvCall se realizó correctamente. El minidirector de red también debe rellenar los datos adecuados en el parámetro SrvCall para la estructura SRV_CALL que se creó. Tenga en cuenta que el parámetro SrvCall pasado a MRxCreateSrvCall es el mismo que el miembro SrvCall en el MRX_SRVCALLDOWN_STRUCTURE del parámetro SrvCallBackContext . Este mismo parámetro SrvCall también se pasa a MRxSrvCallWinnerNotify en el parámetro SrvCall .

La implementación de MRxCreateSrvCall en un minidirector de red también es complicada por la necesidad de controladores de transporte. Ciertas interfaces relacionadas con el transporte requieren que se cree y use un identificador para toda la comunicación. La creación de una estructura de SRV_CALL puede requerir el establecimiento de identificadores relacionados con el transporte para las comunicaciones de red. Dado que el proceso de establecimiento de una conexión de red puede llevar mucho tiempo, una vez establecida una conexión, tiene sentido usar la conexión para la comunicación siempre que sea posible. Una vez establecido un identificador de transporte a un recurso de red remota, se puede reutilizar mediante cualquier número de solicitudes de aplicación. Cuando finaliza una aplicación de usuario, se eliminan los identificadores asociados al proceso. Por este motivo, establecer identificadores de transporte en el contexto de un proceso transitorio en modo usuario que podría ser de corta duración no tiene sentido. Por lo tanto, una estructura de SRV_CALL normalmente debe inicializarse en el contexto de un proceso conocido que no desaparecerá mientras se usan estos controladores de transporte para la comunicación.

Un método que se usa para solucionar los posibles problemas con los controladores de transporte es hacer que el proceso del sistema RDBSS asigne los controladores de transporte. Esto afecta a cómo se ejecuta la rutina MRxCreateSrvCall . Si la solicitud a MRxCreateSrvCall se emitió en el contexto del proceso del sistema RDBSS, esta llamada se puede ejecutar inmediatamente y no es necesario publicarla en una cola de trabajo. Sin embargo, para evitar problemas, si la solicitud a MRxCreateSrvCall procede de cualquier otro proceso, la solicitud se publicaría en una cola de trabajo del sistema mediante RxDispatchToWorkerThread para su posterior ejecución. RDBSS usará más adelante uno de sus subprocesos del sistema para procesar la solicitud de cola de trabajo y ejecutar MRxCreateSrvCall. Esto garantiza que los controladores de transporte sean propiedad de un proceso del sistema.

Un minidirector de red puede determinar si una llamada a MRxCreateSrvCall se recibió directamente desde RDBSS mediante una llamada a RxGetRDBSSProcess. RxGetRDBSSProcess devolverá el proceso RDBBS y este valor se puede comparar con el proceso actual devuelto mediante IoGetCurrentProcess. Si la llamada a MRxCreateSrvCall no se inició en el contexto del proceso del sistema RDBSS, MRxCreateSrvCall puede devolver STATUS_PENDING y publicar la llamada a una cola de trabajo mediante RxDispatchToWorkerThreadpara su ejecución posterior por RDBSS. Normalmente, estas llamadas se publicarían en DelayedWorkQueue.

Es el desarrollador del minidirector de red para decidir cómo se implementa MRxCreateSrvCall . Si el proceso para crear un SRV_CALL puede tardar mucho tiempo, MRxCreateSrvCall debe completarse de forma asincrónica. Si se necesitan controladores de transporte, el minidirector de red debe encontrar un proceso del sistema de larga duración para establecer estos identificadores.

Cuando se complete esta llamada, se debe modificar el parámetro SrvCall con la información de estructura de SRV_CALL actualizada desde el minidirector de red.

Un minidirector de red que indica la compatibilidad como proveedor UNC recibirá una notificación de prefijo del proveedor UNC múltiple (MUP) como una llamada a MRxCreateSrvCall. Para obtener más información sobre la nomenclatura UNC y MUP, consulte Compatibilidad con nomenclatura UNC y MUP.