Função RxStartMinirdr (mrx.h)

Artigo
10/11/2023

RxStartMinirdr é chamado para iniciar um minidiretório de rede que já foi chamado para se registrar no RDBSS. Como parte do RxStartMinirdr, o RDBSS também registrará o driver de minidiretório de rede como um provedor UNC (convenção de nomenclatura universal) com o MUP (Provedor Multi UNC) se o driver indicar suporte para nomes UNC.

Sintaxe

NTSTATUS RxStartMinirdr(
  [in]  IN PRX_CONTEXT RxContext,
  [out] OUT PBOOLEAN   PostToFsp
);

Parâmetros

[in] RxContext

Um ponteiro para a estrutura RX_CONTEXT a ser usada para obter o objeto do dispositivo e determinar se esse é um processo do sistema de arquivos.

[out] PostToFsp

Um ponteiro para um valor lógico definido como TRUE no retorno se a solicitação precisar ser postada para processamento posterior pelo processo do sistema de arquivos.

Retornar valor

RxStartMinirdr retornará STATUS_SUCCESS se a sequência de inicialização tiver sido bem-sucedida ou um dos seguintes valores de erro:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	A solicitação para se registrar como um provedor UNC falhou porque o acesso foi negado.
STATUS_ACCESS_VIOLATION	A solicitação para se registrar como um provedor UNC falhou com uma violação de acesso.
STATUS_INSUFFICIENT_RESOURCES	Não havia recursos suficientes para concluir essa rotina.
STATUS_PENDING	A sequência de inicialização para RDBSS e minidiretórios de rede deve ser concluída no contexto do processo do sistema, não em um processo de aplicativo no modo de usuário. Se a chamada para RxStartMinirdr for proveniente de um processo de modo de usuário (uma solicitação de serviço no modo de usuário, por exemplo), a solicitação será postada para processamento posterior no RDBSS e STATUS_PENDING será retornada. Esse erro também poderá ser retornado se determinados bloqueios rdbss internos não puderem ser adquiridos sem esperar. A chamada será concluída posteriormente de um thread do sistema.
STATUS_REDIRECTOR_STARTED	O minidiretório de rede já foi iniciado.

Comentários

Um minidiretório de rede registra-se com RDBSS sempre que o driver é carregado pelo kernel e, em seguida, cancela o registro com RDBSS quando o driver é descarregado. Um minidiretório de rede informa ao RDBSS que ele foi carregado chamando RxRegisterMinirdr, a rotina de registro exportada do RDBSS. Como parte desse processo de registro, o minidiretório de rede passa um parâmetro para RxRegisterMinirdr que é um ponteiro para uma estrutura grande, MINIRDR_DISPATCH, que contém informações de configuração para o minidiretório de rede e uma tabela de ponteiros para rotinas de retorno de chamada implementadas pelo driver de minidiretório de rede. O RDBSS usa as rotinas de retorno de chamada passadas nessa estrutura para se comunicar com o minidiretório de rede.

O minidiretório de rede não inicia a operação até receber uma chamada para sua rotina MRxStart , uma das rotinas de retorno de chamada passadas na estrutura de MINIRDR_DISPATCH. A rotina de retorno de chamada mrxStart deve ser implementada pelo driver de minidiretório de rede se quiser receber rotinas de retorno de chamada para operações, a menos que o minidiretor de rede preserve seus próprios pontos de entrada de expedição de driver. Caso contrário, o RDBSS permitirá apenas os seguintes pacotes de solicitação de E/S até que o MrxStart retorne com êxito:

Solicitações IRP para operações de criação de dispositivo e operações de dispositivo em que o parâmetro FileObject-FileName.Length> no IRPSP é zero e o parâmetro FileObject-RelatedFileObject> é NULL.

Para qualquer outra solicitação IRP, a rotina de expedição do RDBSS RxFsdDispatch retornará uma status de STATUS_REDIRECTOR_NOT_STARTED.

A rotina de expedição do RDBSS também falhará nas solicitações para os seguintes pacotes de solicitação de E/S:

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

A rotina mrxStart do minidiretório de rede é chamada pelo RDBSS quando a rotina RxStartMinirdr é chamada. A rotina RDBSS RxStartMinirdr geralmente é chamada como resultado de uma solicitação FSCTL ou IOCTL de um aplicativo ou serviço do modo de usuário para iniciar o minidiretório de rede. A chamada para RxStartMinirdr não pode ser feita a partir da rotina DriverEntry do minidiretório de rede após uma chamada bem-sucedida para RxRegisterMinirdr , pois parte do processamento inicial requer que a inicialização do driver seja concluída.

Quando o RDBSS recebe uma solicitação FSCTL ou IOCTL enviada ao driver de minidiretório de rede do modo de usuário, o RDBSS cria uma estrutura RX_CONTEXT e passa essa chamada para a rotina de volta de chamada MRxLowIOSubmit[LOWIO_OP_FSCTL] ou MRxLowIOSubmit[LOWIO_OP_IOCTL] definida na estrutura MINIRDR_DISPATCH. A implementação do minidiretório de rede dessa rotina de back de chamada reconheceria a solicitação para iniciar e chamar RxStartMinirdr. Esse processo normal de eventos é listado abaixo com mais detalhes:

Um aplicativo de modo de usuário emite uma solicitação FSCTL ou IOCTL privada para iniciar o minidiretório de rede.
O driver de kernel RDBSS recebe a solicitação FSCTL ou IOCTL em nome do minidiretório de rede, pois o RDBSS substituiu os pontos de entrada de expedição do driver do driver de minidiretório para apontar para rotinas internas do RDBSS. Observe que isso pressupõe que o minidiretório de rede não definiu o RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH no parâmetro Controls ao chamar RxRegisterMinirdr. Essa opção passada para RxRegisterMinirdr seria incomum e indica que o minidiretório de rede não deseja que o RDBSS substitua seus pontos de entrada de expedição de driver.
O RDBSS recebe a solicitação FSCTL ou IOCTL internamente em nome do redirecionador de rede. O dispatcher RDBSS aloca e inicializa uma estrutura RX_CONTEXT. O RDBSS chama a rotina de minidiretor de rede MRxLowIOSubmit[LOW_OP_FSCTL] ou A rotina MRxLowIOSubmit[LOW_OP_IOCTL] definida na estrutura de MINIRDR_DISPATCH para esse minidiretório de rede, passando a estrutura inicializada RX_CONTEXT como um parâmetro.
A implementação do minidiretório de rede dessa rotina de back de chamada reconheceria a solicitação privada FSCTL ou IOCTL para iniciar e chamar RxStartMinirdr, passando um ponteiro para a estrutura RX_CONTEXT recebida do RDBSS como o parâmetro RxContext e o endereço do membro PostToFSP de RxContext como o parâmetro PostToFsp .
Como essa chamada foi iniciada do modo de usuário, RxStartMinirdr retornaria STATUS_PENDING e definiria PostToFsp como TRUE.
A rotina de minidiretório de rede MRxLowIOSubmit[LOW_OP_FSCTL] ou MRxLowIOSubmit[LOW_OP_IOCTL] receberia esse valor retornado e o passaria de volta para o dispatcher rdbss.
O dispatcher rdbss receberia o valor retornado STATUS_PENDING e definiria PostToFsp como TRUE e, em seguida, postaria uma solicitação em um thread de trabalho para executar novamente a chamada para o minidiretório de rede.

Após esse ponto, há dois resultados possíveis com base em se o FSCTL ou IOCTL foi solicitado como uma operação assíncrona ou síncrona.

Se essa fosse uma solicitação assíncrona, o seguinte ocorreria:

O chamador do modo de usuário receberia a resposta STATUS_PENDING da chamada. O thread de trabalho postado eventualmente chamaria RxStartMinirdr de um thread do sistema de arquivos e a chamada seria processada. A rotina RxStartMinirdr tentará registrar o minidiretório de rede como um provedor UNC, se solicitado. Em versões do Windows anteriores ao Windows Vista, o RDBSS tentará registrar o minidiretório de rede como um sistema de arquivos com o gerenciador de E/S. Se essas chamadas forem bem-sucedidas, o RxStartMinirdr chamará a rotina de retorno de chamada MrxStart implementada pelo minidiretório de rede. O valor retornado de MrxStart eventualmente seria retornado para o aplicativo de modo de usuário que iniciou o processo de sequência de chamadas como uma operação assíncrona.

Se essa fosse uma solicitação síncrona, o seguinte ocorreria:

O chamador do modo de usuário não receberia a resposta STATUS_PENDING, mas seria forçado a aguardar até que a chamada retornasse do thread de trabalho postado. O thread de trabalho postado eventualmente chamaria RxStartMinirdr de um thread do sistema de arquivos e a chamada seria processada. A rotina RxStartMinirdr tentará registrar o minidiretório de rede como um provedor UNC, se solicitado. Em versões do Windows anteriores ao Windows Vista, o RDBSS tentará registrar o minidiretório de rede como um sistema de arquivos com o gerenciador de E/S. Se essas chamadas forem bem-sucedidas, o RxStartMinirdr chamará a rotina de retorno de chamada MrxStart implementada pelo minidiretório de rede. O valor retornado de MrxStart seria retornado para o aplicativo de modo de usuário que iniciou o processo de sequência de chamadas.

Se um minidiretório de rede indicar suporte para UNC ao registrar com RDBSS (o parâmetro Controls para RxRegisterMinirdr), rxStartMinirdr tentará registrar o parâmetro DeviceName do minidiretório de rede como um provedor UNC com MUP (o RDBSS chama FsRtlRegisterUncProvider em nome do minidiretório de rede).

Em versões do Windows anteriores ao Windows Vista, o RxStartMinirdr registra o sistema de arquivos com o gerenciador de E/S (o RDBSS chama IoRegisterFileSystem em nome do minidiretório de rede).

Se as chamadas forem bem-sucedidas, rxStartMinirdr chamará a rotina de mrxStart de minidiretório de rede. Se MrxStart retornar êxito, o estado interno do minidiretório no RDBSS será definido como RDBSS_STARTED. O membro StartStopContext.Version do objeto de dispositivo minidiretório também será incrementado.

A sequência de inicialização para RDBSS e o minidiretório de rede deve ser concluída no contexto do processo do sistema se a operação assíncrona for solicitada. Se a chamada para RxStartMinirdr for proveniente de um processo de modo de usuário (uma solicitação de serviço de modo de usuário, por exemplo), a solicitação será postada internamente pelo RDBSS em uma fila de trabalho para processamento posterior e STATUS_PENDING será retornado e o parâmetro PostToFsp será definido como TRUE. Além disso, se determinados bloqueios rdbss internos não puderem ser obtidos sem esperar, STATUS_PENDING será retornado e PostToFsp será definido como TRUE. Quando STATUS_PENDING for retornado, RxStartMinirdr será chamado novamente de dentro de um processo do sistema. Se a solicitação FSCTL ou IOCTL que iniciou a chamada para RxStartMinirdr tiver sido definida para operação assíncrona, o RDBSS retornará STATUS_PENDING fazer backup da cadeia de chamadas para a solicitação FSCTL ou IOCTL original do modo de usuário. Por outro lado, se a solicitação FSCTL ou IOCTL fosse para operação síncrona, a chamada também seria postada em um thread de trabalho para execução posterior, mas a chamada FSCTL ou IOCTL não retornaria ao modo de usuário até que RxStartMinirdr tivesse sido executado no contexto do processo do sistema de arquivos. Nesse caso, o chamador do FSCTL ou IOCTL nunca veria o erro STATUS_PENDING retornar. O comportamento mais típico é iniciar uma solicitação síncrona para essas operações de início/parada para simplificar o código do aplicativo no modo de usuário.

Em uma terminação anormal ou outra falha, o RxStartMinirdr tentará desfazer essas operações, incluindo o cancelamento do registro do provedor UNC com MUP, o cancelamento do registro do sistema de arquivos, a liberação de memória alocada para armazenar o nome de domínio a ser usado por transmissões de emaillot e a atualização de tabelas RDBSS internas.