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

Artigo
02/29/2024

A rotina MRxCreateSrvCall é chamada pelo RDBSS para solicitar que o minidiretório de rede crie uma estrutura SRV_CALL e estabeleça a conexão com um servidor.

Sintaxe

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

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

Parâmetros

SrvCall

[in, out] Um ponteiro para a estrutura SRV_CALL a ser criada.

SrvCallCallBackContext

[in, out] Um ponteiro para o contexto de retorno de chamada usado pelo minidiretório de rede para notificar o RDBSS quando a solicitação MRxCreateSrvCall for finalmente concluída. O parâmetro SrvCallCallBackContext aponta para uma estrutura MRX_SRVCALLDOWN_STRUCTURE que contém a estrutura RX_CONTEXT para essa solicitação, bem como a rotina de retorno de chamada que o minidiretório chama quando a solicitação MRxCreateSrvCall é finalmente concluída.

Retornar valor

O RDBSS espera que MRxCreateSrvCall 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 MRxCreateSrvCall.

A status final de conclusão é retornada no membro SrvCallCallBackContext-Status> depois que a chamada é concluída e a rotina no membro de Retorno de Chamada na estrutura MRX_SRVCALLDOWN_STRUCTURE é chamada pelo minidiretório de rede. Inicialmente, esse membro contém STATUS_BAD_NETWORK_PATH até que o minidiretório de rede altere esse valor após a conclusão.

O membro SrvCallCallBackContext-Status> contém STATUS_SUCCESS após a conclusão da chamada ou um dos seguintes códigos de erro comuns sobre falha (embora outros códigos de erro sejam possíveis):

Código de retorno	Descrição
STATUS_BAD_NETWORK_PATH	O caminho de rede especificado é inválido.
STATUS_NETWORK_UNREACHABLE	A rede era inacessível.

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. Uma estrutura SRV_CALL corresponde ao contexto associado a um servidor depois que uma conexão é estabelecida. Uma estrutura NET_ROOT corresponde a um compartilhamento em um servidor (isso também pode ser exibido como uma parte do namespace que foi reivindicado por um minidiretório de rede).

A criação de uma estrutura de SRV_CALL 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 SRV_CALL é modelada como uma atividade de duas fases. Cada chamada para um minidiretório de rede para criar uma estrutura SRV_CALL é acompanhada por uma chamada do minidiretório de rede para RDBSS que especifica o status de conclusão da solicitação. O RDBSS pressupõe que MRxCreateSrvCall será concluído de forma assíncrona. Portanto, o RDBSS espera que MRxCreateSrvCall retorne STATUS_PENDING. O RDBSS será notificado usando a rotina de retorno de chamada quando a chamada finalmente for concluída.

Espera-se que uma implementação de minidiretório de rede MRxCreateSrvCall retorne STATUS_PENDING à chamada inicial. Quando o processamento é concluído, o minidiretório de rede chama a rotina de retorno de chamada que é passada como parte do parâmetro SrvCallCallBackContext para notificar o RDBSS de que a chamada foi concluída e retornar o status de conclusão. A rotina de retorno de chamada que o minidiretor de rede chama é especificada como o membro de retorno de chamada no MRX_SRVCALLDOWN_STRUCTURE do parâmetro SrvCallCallBackContext . O status final de conclusão da chamada deve ser armazenado no membro Status do parâmetro SrvCallCallBackContext.

Com êxito, o minidiretório de rede também deve armazenar algum valor no membro RecommunicateContext do SrvCallCallBackContext. O valor armazenado no membro RecommunicateContext é o valor que o RDBSS passará para MRxSrvCallWinnerNotify no parâmetro RecommunicateContext se MRxCreateSrvCall tiver sido bem-sucedido. O minidiretório de rede também deve preencher os dados apropriados no parâmetro SrvCall para a estrutura de SRV_CALL que foi criada. Observe que o parâmetro SrvCall passado para MRxCreateSrvCall é o mesmo que o membro SrvCall no MRX_SRVCALLDOWN_STRUCTURE do parâmetro SrvCallCallBackContext . Esse mesmo parâmetro SrvCall também é passado para MRxSrvCallWinnerNotify no parâmetro SrvCall .

A implementação de MRxCreateSrvCall 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 SRV_CALL 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 SRV_CALL 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 contornar os possíveis problemas com identificadores de transporte é fazer com que o processo do sistema RDBSS aloque as alças de transporte. Isso afeta como a rotina MRxCreateSrvCall é executada. Se a solicitação para MRxCreateSrvCall 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 MRxCreateSrvCall 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 MRxCreateSrvCall. 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 MRxCreateSrvCall foi recebida diretamente do RDBSS chamando RxGetRDBSSProcess. RxGetRDBSSProcess retornará o processo RDBBS e esse valor pode ser comparado com o processo atual retornado usando IoGetCurrentProcess. Se a chamada para MRxCreateSrvCall não tiver sido iniciada no contexto do processo do sistema RDBSS, MRxCreateSrvCall poderá retornar STATUS_PENDING e postar a chamada em uma fila de trabalho usando RxDispatchToWorkerThreadpara execução posterior pelo RDBSS. Normalmente, essas chamadas seriam postadas no DelayedWorkQueue.

Cabe ao desenvolvedor do minidiretório de rede decidir como MRxCreateSrvCall é implementado. Se o processo para criar um SRV_CALL puder levar uma quantidade considerável de tempo, MRxCreateSrvCall deverá ser concluído de forma assíncrona. Se as alças de transporte forem necessárias, o minidiretório de rede precisará encontrar um processo do sistema que seja de longa duração para estabelecer esses identificadores.

Quando essa chamada for concluída, o parâmetro SrvCall deverá ser modificado com as informações de estrutura SRV_CALL atualizadas do minidiretório de rede.

Um minidiretório de rede que indica suporte como um provedor UNC receberá uma declaração de prefixo do MUP (Provedor Multi UNC) como uma chamada para MRxCreateSrvCall. Para obter mais informações sobre Nomeação UNC e MUP, consulte Suporte para nomenclatura UNC e MUP.