Função RxRegisterMinirdr (mrx.h)

Artigo
08/07/2023

RxRegisterMinirdr é chamado por um driver de minidiretório de rede para registrar o driver no RDBSS, o que adiciona as informações de registro a uma tabela de registro interna. O RDBSS também cria um objeto de dispositivo para o minidiretório de rede.

Sintaxe

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

Parâmetros

[out] DeviceObject

Um ponteiro para onde o objeto de dispositivo criado será armazenado.

[in, out] DriverObject

Um ponteiro para o objeto de driver do driver de minidiretório de rede. Cada driver recebe um ponteiro para seu objeto de driver em um parâmetro para sua rotina DriverEntry . Esse objeto de driver será usado para criar o objeto de dispositivo para o driver de minidiretório de rede.

[in] MrdrDispatch

Um ponteiro para a tabela de expedição para o minidiretório de rede. Esta tabela de expedição inclui 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 kernel de minidiretório de rede. O RDBSS faz chamadas para o driver de minidiretório de rede por meio dessa lista de rotinas de retorno de chamada.

[in] Controls

O conjunto de opções que determinam os recursos do driver de minidiretório de rede e como o RDBSS deve lidar com a inicialização e o cache de tabela de nomes para o driver de minidiretório de rede. Essas opções podem incluir qualquer combinação dos seguintes bits:

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

Quando esse sinalizador é definido, ele indica que o minidiretório de rede não dá suporte a nomes UNC.

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

Quando esse sinalizador é definido, ele indica que o minidiretório de rede não dá suporte a emailslots.

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

Quando esse sinalizador é definido, ele indica que o minidiretório de rede não deseja que o RDBSS inicialize os pontos de entrada de expedição do driver do driver de minidiretório para apontar para rotinas internas do RDBSS. Essa opção só seria usada em circunstâncias incomuns. Normalmente, o RDBSS definiria os pontos de entrada de expedição do driver e a expedição rápida de E/S no objeto de driver de minidiretório de rede para apontar para rotinas internas para RDBSS.

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

Quando esse sinalizador é definido, ele indica que o minidiretório de rede não deseja que o RDBSS inicialize sua tabela de nomes de rede interna e estruturas de dados de catador para limpar essa tabela de nomes. Essa opção seria definida para um minidiretório de rede que deseja lidar com o cache para nomes de compartilhamento de rede em si e não usar as instalações do RDBSS para cache e limpeza de nomes.

[in] DeviceName

Um ponteiro para um buffer que contém uma cadeia de caracteres Unicode terminada em zero que nomeia o objeto do dispositivo. A cadeia de caracteres deve ser um nome de caminho completo. Esse parâmetro é passado como DeviceName para a rotina IoCreateDevice pelo RDBSS.

[in] DeviceExtensionSize

O tamanho especificado pelo driver de minidiretório para o número de bytes a serem alocados para a extensão de dispositivo do objeto do dispositivo. A estrutura interna da extensão do dispositivo é definida pelo driver. Esse parâmetro é adicionado ao tamanho da extensão de dispositivo usada pelo RDBSS e passado como o parâmetro DeviceExtensionSize para a rotina IoCreateDevice pelo RDBSS.

[in] DeviceType

O tipo de dispositivo usado quando o objeto de dispositivo é criado. Isso especifica uma das constantes de FILE_DEVICE_XXX definidas pelo sistema que indicam o tipo de dispositivo ou um valor definido pelo fornecedor para um novo tipo de dispositivo. Normalmente, esse valor seria FILE_DEVICE_NETWORK_FILE_SYSTEM para drivers de minidiretório de rede. Esse parâmetro é passado como DeviceType para a rotina IoCreateDevice pelo RDBSS.

[in] DeviceCharacteristics

As características do dispositivo usadas quando o objeto de dispositivo é criado. Isso especifica uma ou mais constantes definidas pelo sistema, combinadas, que fornecem informações adicionais sobre o dispositivo do driver. Esse valor deve incluir FILE_REMOTE_DEVICE para drivers de minidiretório de rede, mas isso pode ser combinado com outras características, como FILE_DEVICE_SECURE_OPEN. Esse parâmetro é passado como DeviceCharacteristics para a rotina IoCreateDevice pelo RDBSS.

Retornar valor

RxRegisterMinirdr retorna STATUS_SUCCESS com êxito ou um dos seguintes valores de erro em caso de falha:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	Não havia recursos suficientes para criar o objeto de dispositivo.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi passado para a rotina. Esse erro será retornado se o parâmetro DeviceObject for um ponteiro NULL .
STATUS_OBJECT_NAME_COLLISION	Ocorreu uma colisão de nome ao tentar criar esse objeto de dispositivo.
STATUS_OBJECT_NAME_EXISTS	Já existe um objeto de dispositivo com esse nome.
STATUS_UNSUCCESSFUL	A chamada para criar o objeto de dispositivo retornou um objeto de dispositivo NULL .

Comentários

Um minidiretório de rede registra-se com RDBSS sempre que o driver é carregado pelo kernel e cancela o registro com RDBSS quando o driver é descarregado. Um driver não monolítico (o minidiretório de rede SMB) se comunica com o Rdbss.sys, outro driver de kernel. Para um driver de minidiretório de rede monolítico que se vincula estaticamente a Rdbsslib.lib, essa comunicação é apenas uma chamada para uma rotina de biblioteca Rdbsslib.lib .

Um minidiretório de rede informa ao RDBSS que ele foi carregado chamando RxRegisterMinirdr, a rotina de registro exportada do RDBSS. Quando um driver de minidiretório de rede é iniciado pela primeira vez (em sua rotina DriverEntry ), o driver chama a rotina RDBSS RxRegisterMinirdr para registrar o driver de minidiretório de rede com RDBSS. Com base nos parâmetros passados para RxRegisterMinirdr, o RDBSS chama IoCreateDevice para criar o objeto de dispositivo para o driver de minidiretório de rede.

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 expedição de ponteiros para rotinas de retorno de chamada implementadas pelo driver de minidiretório de rede. Esses dados de configuração são usados para configurar tabelas RDBSS internas para uso com esse 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. Um minidiretório de rede pode optar por implementar apenas algumas dessas rotinas de retorno de chamada. Qualquer rotina de retorno de chamada que não seja implementada deve ser definida como um ponteiro NULL na tabela de expedição passada para RDBSS. Somente as rotinas de retorno de chamada implementadas pelo minidiretório de rede serão chamadas pelo RDBSS.

Observe que a rotina RxRegisterMinirdr define todas as rotinas de expedição de driver do driver de minidiretório de rede para apontar para a rotina de expedição rdbss de nível superior, RxFsdDispatch. Um minidiretório de rede pode substituir esse comportamento salvando uma cópia de seus pontos de entrada de expedição de driver, chamando RxRegisterMinirdr e reescrevendo a expedição do driver com seus próprios pontos de entrada após o retorno da chamada para RxRegisterMinirdr . Um minidiretório de rede também pode impedir que suas rotinas de expedição de driver sejam copiadas pela rotina RxRegisterMinirdr se o bit RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH estiver definido no parâmetro Controls .

Se a chamada RxRegisterMinirdr for bem-sucedida, vários membros em RDBSS_DEVICE_OBJECT apontados pelo parâmetro DeviceObject serão inicializados, incluindo o seguinte:

O membro Dispatch é definido como o parâmetro MrdrDispatch .
O membro RegistrationControls é definido como o parâmetro Controls .
O membro DeviceName é definido como o parâmetro DeviceName .
O membro RegisterUncProvider será definido como TRUE se o RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS bit no parâmetro Controls não tiver sido definido.
O membro RegisterMailSlotProvider será definido como TRUE se o RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS bit no parâmetro Controls não tiver sido definido.
O membro NetworkProviderPriority é definido como a prioridade do provedor de rede que o MUP usará.

Se a chamada RxRegisterMinirdr for bem-sucedida e o bit RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER no parâmetro Controls não estiver definido, vários outros membros em RDBSS_DEVICE_OBJECT apontados pelo parâmetro DeviceObject serão inicializados, incluindo o seguinte:

A estrutura de membros pRxNetNameTable é inicializada.
O membro RxNetNameTableInDeviceObject.IsNetNameTable está definido como TRUE.
A estrutura de membro pRdbssScavenger é inicializada.

Se a chamada RxRegisterMinirdr for bem-sucedida, o RDBSS definirá o estado interno do minidiretório de rede no RDBSS como RDBSS_STARTABLE.

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 MINIRDR_DISPATCH. A rotina de retorno de chamada mrxStart deve ser implementada pelo driver de minidiretório de rede se quiser receber retornos 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 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

A rotina MrxStart do minidiretor de rede é chamada pelo RDBSS quando a rotina RxStartMiniRdr é chamada. O RDBSS RxStartMinirdr geralmente é chamado 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 porque parte do processamento inicial requer que a inicialização do driver seja concluída. Depois que a chamada RxStartMinirdr é recebida, o RDBSS conclui o processo de início chamando a rotina MrxStart do minidiretório de rede. Se a chamada para MrxStart retornar êxito, o RDBSS definirá o estado interno do minidiretório no RDBSS como RDBSS_STARTED.