PMRX_CREATE_V_NET_ROOT função de retorno de chamada (mrx.h)

Artigo
10/13/2023

A rotina MRxCreateVNetRoot é chamada pelo RDBSS para solicitar que o minidiretório de rede crie uma estrutura V_NET_ROOT e, em alguns casos, uma estrutura NET_ROOT.

Sintaxe

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

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

Parâmetros

Context

[in, out] Um ponteiro para o contexto de retorno de chamada usado pelo minidiretório de rede para notificar o RDBSS quando a chamada for finalmente concluída. Isso inclui a estrutura RX_CONTEXT da solicitação em Context-RxContext>. O parâmetro Context inclui a estrutura V_NET_ROOT a ser construída em Context-pVNetRoot>. Essa estrutura V_NET_ROOT contém um ponteiro para a estrutura NET_ROOT em pVNetRoot-pNetRoot>. A estrutura NET_ROOT também contém um ponteiro para a estrutura SRV_CALL em pNetRoot-pSrvCall>.

Retornar valor

O RDBSS espera que MRxCreateVNetRoot retorne STATUS_PENDING em caso de êxito ou falha. Esse comportamento resulta porque o RDBSS espera que essa chamada seja concluída de forma assíncrona. Um minidiretório de rede deve mapear STATUS_SUCCESS para STATUS_PENDING como um valor retornado para MRxCreateVNetRoot.

A status final de conclusão é retornada nos membros Context-VirtualNetRootStatus> e Context-NetRootStatus> após a conclusão da chamada e a rotina no membro de retorno de chamada da estrutura contextual é chamada pelo minidiretório de rede. Inicialmente, esses membros contêm STATUS_SUCCESS até que o minidiretório de rede altere esse valor após a conclusão. Se a chamada for concluída com êxito, ambos os membros conterão STATUS_SUCCESS.

Ao não criar uma estrutura de V_NET_ROOT ou NET_ROOT, um dos seguintes códigos de erro comuns para o membroVirtualNetRootStatus ou NetRootStatus é retornado (embora outros códigos de erro sejam possíveis):

Código de retorno	Descrição
STATUS_CONNECTION_RESET	A conexão com o recurso remoto foi redefinida.
STATUS_IO_TIMEOUT	Um tempo limite ocorreu em uma solicitação de E/S.
STATUS_RETRY	Um servidor de inicialização remota não estava pronto para atender à solicitação.
STATUS_UNEXPECTED_NETWORK_ERROR	Geralmente, ocorreu um erro de rede inesperado causado por um identificador inválido.

Comentários

As duas abstrações importantes usadas na interface entre RDBSS e um minidiretório de rede são a estrutura SRV_CALL e a estrutura NET_ROOT/V_NET_ROOT. Uma estrutura SRV_CALL corresponde ao contexto associado a um servidor com o qual uma conexão foi estabelecida. Uma estrutura NET_ROOT corresponde a um compartilhamento em um servidor. Uma estrutura V_NET_ROOT pode ser exibida como uma parte do namespace abaixo de uma estrutura NET_ROOT reivindicada por um minidiretório de rede.

A criação de uma estrutura de NET_ROOT/V_NET_ROOT normalmente envolve pelo menos uma viagem de ida e volta de rede. Essa operação pode levar um tempo considerável para ser concluída porque uma conexão de rede com um recurso remoto pode precisar ser estabelecida. Para garantir que as operações assíncronas continuem, a criação de uma estrutura NET_ROOT/V_NET_ROOT é modelada como uma atividade de duas fases. Cada chamada para um minidiretório de rede para criar uma estrutura NET_ROOT/V_NET_ROOT é seguida por uma chamada de volta do minidiretório de rede para RDBSS que indica ao RDBSS o status de conclusão da solicitação para o minidiretório de rede. Como o RDBSS espera que MRxCreateVNetRoot seja concluído de forma assíncrona, o RDBSS espera que MRxCreateVNetRoot retorne STATUS_PENDING. O RDBSS será notificado usando a rotina de retorno de chamada quando a chamada finalmente for concluída.

MRxCreateVNetRoot deve lidar com dois casos de interesse:

Uma nova estrutura de V_NET_ROOT e a nova estrutura de NET_ROOT associada estão sendo criadas.
Uma nova estrutura V_NET_ROOT associada a uma estrutura de NET_ROOT existente está sendo criada.

Esses dois casos podem ser diferenciados verificando se o contexto associado a uma estrutura de NET_ROOT é NULL.

Espera-se que uma implementação de minidiretório de rede de MRxCreateVNetRoot retorne STATUS_PENDING à chamada inicial. Quando o processamento for concluído, o minidiretório de rede chamará a rotina de retorno de chamada passada como parte do parâmetro Context para notificar o RDBSS de que a chamada foi concluída e retornar o status de conclusão. A rotina de retorno de chamada para a qual o minidiretor de rede deve chamar é especificada como o membro de retorno de chamada na estrutura MRX_CREATENETROOT_CONTEXT passada como o parâmetro Context . O status final de conclusão da chamada MRxCreateVNetRoot deve ser armazenado nos membros VirtualNetRootStatus e NetRootStatus do parâmetro Context. Observe que status separados são retornados para as estruturas NET_ROOT e V_NET_ROOT.

A implementação de MRxCreateVNetRoot em um minidiretório de rede também é complicada pela necessidade de identificadores de transporte. Determinadas interfaces relacionadas ao transporte exigem que um identificador seja criado e usado para toda a comunicação. A criação de uma estrutura de NET_ROOT ou V_NET_ROOT pode exigir o estabelecimento de identificadores relacionados ao transporte para comunicações de rede. Como o processo de estabelecer uma conexão de rede pode ser demorado, uma vez estabelecida uma conexão, faz sentido usar a conexão para comunicação o maior tempo possível. Depois que um identificador de transporte para um recurso de rede remota é estabelecido, ele pode ser reutilizado por qualquer número de outras solicitações de aplicativo. Quando um aplicativo de usuário é encerrado, os identificadores associados ao processo são excluídos. Por esse motivo, estabelecer identificadores de transporte no contexto de um processo transitório de modo de usuário que pode ser de curta duração não faz sentido. Portanto, uma estrutura de NET_ROOT ou V_NET_ROOT normalmente precisa ser inicializada no contexto de um processo conhecido que não desaparecerá enquanto essas alças de transporte estiverem sendo usadas para comunicação.

Um método usado para gerenciar isso em minidiretórios de rede é fazer com que o processo do sistema RDBSS aloque esses identificadores de transporte. Isso afeta como a rotina MRxCreateVNetRoot é executada. Se a solicitação para MRxCreateVNetRoot tiver sido emitida no contexto do processo do sistema RDBSS, essa chamada poderá ser executada imediatamente e não precisará ser postada em uma fila de trabalho. No entanto, para evitar problemas, se a solicitação para MRxCreateVNetRoot for de qualquer outro processo, a solicitação será postada em uma fila de trabalho do sistema usando RxDispatchToWorkerThread para execução posterior. O RDBSS usará posteriormente um de seus threads do sistema para processar a solicitação da fila de trabalho e executar MRxCreateVNetRoot. Isso garante que todas as alças de transporte sejam de propriedade de um processo do sistema.

Um minidiretório de rede pode determinar se uma chamada para MRxCreateVNetRoot foi recebida diretamente do RDBSS chamando RxGetRDBSSProcess. RxGetRDBSSProcess retorna o processo RDBBS e esse valor pode ser comparado com o processo atual retornado chamando IoGetCurrentProcess. Se a chamada para MRxCreateVNetRoot não tiver sido iniciada no contexto do processo do sistema RDBSS, MRxCreateVNetRoot poderá retornar STATUS_PENDING e postar a chamada em uma fila de trabalho usando RxDispatchToWorkerThread para execução posterior pelo RDBSS. Normalmente, essas chamadas seriam postadas no DelayedWorkQueue.

Cabe ao minidiretório de rede decidir como MRxCreateVNetRoot é implementado. Se esse processo puder levar uma quantidade considerável de tempo, essa chamada deverá ser concluída de forma assíncrona. Se as alças de transporte forem necessárias, o minidiretório de rede poderá querer um processo do sistema que tenha vida longa para estabelecer esses identificadores.

Caso a conexão não possa ser estabelecida, o minidiretório de rede poderá tentar fazer a transição do NET_ROOT e V_NET_ROOT estruturas para um modo desconectado (se houver suporte) e estabelecer a conexão offline.

Quando MRxCreateVNetRoot for concluído, o parâmetro Context deverá ser modificado com as informações de estrutura de NET_ROOT e V_NET_ROOT apropriadas atualizadas do minidiretório de rede.