Função RxStartMinirdr (mrx.h)

Artigo
02/07/2025

RxStartMinirdr é chamado para iniciar um minidiretório de rede chamado anteriormente para se registrar no RDBSS. Como parte do RxStartMinirdr, o RDBSS também registrará o driver de minidiretor 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.

Valor de retorno

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.

Observações

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 de MRxStart, uma das rotinas de retorno de chamada passadas na estrutura MINIRDR_DISPATCH. O MrxStart rotina de retorno de chamada deve ser implementado pelo driver de minidiretório de rede se desejar receber rotinas de retorno de chamada para operações, a menos que o minidiretório de rede preserve seus próprios pontos de entrada de expedição de driver. Caso contrário, o RDBSS só permitirá 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á um status de STATUS_REDIRECTOR_NOT_STARTED.

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

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

O minidiretor de rede rotina de MrxStart é chamado pelo RDBSS quando a rotina de RxStartMinirdr é chamada. A rotina de RxStartMinirdr RDBSS geralmente é chamada como resultado de uma solicitação FSCTL ou IOCTL de um aplicativo ou serviço no 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 o do minidiretório de rede MRxLowIOSubmit[LOWIO_OP_FSCTL] ou MRxLowIOSubmit[LOWIO_OP_IOCTL] rotina de chamada definida na estrutura de 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 privada ou IOCTL 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, uma vez que 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 controles 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 de RX_CONTEXT. O RDBSS chama o minidiretor de rede MRxLowIOSubmit[LOW_OP_FSCTL] ou MRxLowIOSubmit[LOW_OP_IOCTL] rotina definida na estrutura MINIRDR_DISPATCH para esse minidiretório de rede, passando a estrutura inicializada RX_CONTEXT como um parâmetro.
A implementação do minidiretor 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 PostToFSP membro do 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.
O minidiretório de rede MRxLowIOSubmit[LOW_OP_FSCTL] ou MRxLowIOSubmit[LOW_OP_IOCTL] rotina receberia esse valor retornado e o passaria de volta para o dispatcher RDBSS.
O dispatcher do 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 de 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, RxStartMinirdr chamará o mrxStart rotina de retorno de chamada 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 de 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, RxStartMinirdr chamará o mrxStart rotina de retorno de chamada 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 se registrar no RDBSS (o parâmetro Controls para RxRegisterMinirdr), RxStartMinirdr tentará para registrar o parâmetro DeviceName do minidiretório de rede como um provedor UNC com MUP (chamadas RDBSS FsRtlRegisterUncProvider em nome do minidiretório de rede).

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

Se as chamadas forem bem-sucedidas, RxStartMinirdr chamará o minidiretório de rede rotina de MrxStart. Se MrxStart retornar êxito, o estado interno do minidiretório no RDBSS será definido como RDBSS_STARTED. O StartStopContext.Version membro do objeto de dispositivo de 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 estiver definido como TRUE. Quando STATUS_PENDING é 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 foi definida para operação assíncrona, o RDBSS retornaria 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 executada no contexto do processo do sistema de arquivos. Nesse caso, o chamador do FSCTL ou IOCTL nunca veria a STATUS_PENDING retorno de erro. 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, 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.