Função FsRtlRegisterUncProviderEx (ntifs.h)

Artigo
02/26/2024

A rotina FsRtlRegisterUncProviderEx registra um redirecionador de rede como um provedor UNC (convenção de nomenclatura universal) com o sistema de vários provedores UNC (MUP).

Sintaxe

NTSTATUS FsRtlRegisterUncProviderEx(
  [out] PHANDLE                  MupHandle,
  [in]  PCUNICODE_STRING         RedirDevName,
  [in]  PDEVICE_OBJECT           DeviceObject,
  [in]  FSRTL_UNC_PROVIDER_FLAGS Flags
);

Parâmetros

[out] MupHandle

Um ponteiro para um local no qual retornar um identificador MUP a ser usado ao chamar FsRtlDeregisterUncProvider para desregistrar o redirecionador de rede. O identificador retornado será válido somente se FsRtlRegisterUncProviderEx retornar STATUS_SUCCESS.

[in] RedirDevName

Um ponteiro para uma cadeia de caracteres Unicode que contém o nome do dispositivo do redirecionador de rede. O MUP usa esse nome de dispositivo para criar um link simbólico no namespace do Gerenciador de Objetos cujo destino é \Device\Mup.

[in] DeviceObject

Um ponteiro para um objeto de dispositivo sem nome que representa o redirecionador de rede.

[in] Flags

Uma máscara de bits que indica os recursos compatíveis com o redirecionador de rede. Um redirecionador de rede define um bit para indicar que há suporte para um recurso. O parâmetro Flags tem duas opções:

FSRTL_UNC_PROVIDER_FLAGS_MAILSLOTS_SUPPORTED

O redirecionador de rede dá suporte a emailslots. Essa opção normalmente é reservada para uso pelo redirecionador SMB da Microsoft.

FSRTL_UNC_PROVIDER_FLAGS_CSC_ENABLED

O redirecionador de rede dá suporte ao acesso offline usando o cache do lado do cliente.

Retornar valor

FsRtlRegisterUncProviderEx retorna STATUS_SUCCESS com êxito ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	O modo solicitante do IRP enviado ao MUP não era do modo kernel.
STATUS_ACCESS_VIOLATION	Ocorreu uma violação de acesso ao tentar acessar o dispositivo MUP.
STATUS_DATATYPE_MISALIGNMENT	Houve um desalinhamento de dados.
STATUS_INSUFFICIENT_RESOURCES	Não havia recursos suficientes disponíveis para alocar memória para buffers.
STATUS_INVALID_DEVICE_REQUEST	Foi feita uma solicitação para registrar um provedor conhecido que já estava registrado.
STATUS_INVALID_PARAMETER	O parâmetro RedirDevName era inválido porque o comprimento de RedirDevName era zero.
STATUS_OBJECT_TYPE_MISMATCH	Uma incompatibilidade de tipo de objeto foi encontrada com o parâmetro DeviceObject .

Comentários

Um redirecionador de rede deve se registrar com o MUP (provedor unc múltiplo) para lidar com nomes UNC (Convenção de Nomenclatura Universal). O MUP é um componente do modo kernel responsável por canalizar todos os acessos remotos do sistema de arquivos usando um nome UNC (Convenção Universal de Nomenclatura) para um redirecionador de rede (o provedor UNC) capaz de lidar com as solicitações do sistema de arquivos remoto. O MUP está envolvido quando um caminho UNC é usado por um aplicativo, conforme ilustrado pelo exemplo a seguir, que pode ser executado a partir de uma linha de comando:

notepad \\server\public\readme.txt

O MUP não está envolvido durante uma operação que cria uma letra de unidade mapeada (o comando "NET USE", por exemplo). Essa operação é tratada pelo MPR (roteador de vários provedores) e uma DLL do provedor WNet no modo de usuário para o redirecionador de rede. No entanto, uma DLL do provedor WNet no modo de usuário pode se comunicar diretamente com um driver de redirecionamento de rede no modo kernel durante essa operação.

Para redirecionadores de rede que estão em conformidade com o modelo de redirecionamento do Windows Vista, o MUP está envolvido mesmo quando uma unidade de rede mapeada é usada. As operações de arquivo executadas na unidade mapeada passam pelo MUP até o redirecionador de rede. Observe que, nesse caso, o MUP simplesmente passa a operação para o redirecionador de rede envolvido.

FsRtlRegisterUncProviderEx envia um FSCTL (controle do sistema de arquivos privado) ao MUP para executar o registro.

O nome do dispositivo especificado no parâmetro RedirDevName na chamada para FsRtlRegisterUncProviderEx torna-se um link simbólico para \device\Mup no namespace do gerenciador de objetos. Além disso, uma solicitação aberta do nome do dispositivo, RedirDevName, roteará-se para o objeto real do dispositivo de redirecionamento de rede apontado pelo parâmetro DeviceObject .

Os redirecionadores de rede que chamam FsRtlRegisterUncProviderEx não devem se registrar como um sistema de arquivos (os redirecionadores de rede não devem chamar IoRegisterFileSystem). Os minidiretórios de rede que usam o RDBSS do Windows Vista (vinculação dinâmica ou estática) não serão registrados como um sistema de arquivos.

Objetos de arquivo na pilha do sistema de arquivos remoto de propriedade de um redirecionador de rede que está em conformidade com o modelo de redirecionamento do Windows Vista resolve para MUP. Portanto, IoGetDeviceAttachmentBaseRef retorna o objeto de dispositivo para MUP, não o redirecionador de rede que possui o objeto de arquivo. No entanto, o conteúdo do objeto de arquivo ainda pertence ao redirecionador de rede.

O valor do registro ProviderOrder determina a ordem na qual o MUP emite solicitações de resolução de prefixo para redirecionadores de rede individuais. Essa ordem pode ser alterada dinamicamente sem uma reinicialização. Esse valor do Registro está localizado sob a seguinte chave do Registro:

HKLM\CurrentControlSet\Control\NetworkProvider\Order

Somente um provedor de rede em um sistema pode dar suporte a emailslots. Portanto, a opção FSRTL_UNC_PROVIDER_FLAGS_MAILSLOTS_SUPPORTED no parâmetro Flags normalmente é definida apenas para o redirecionador SMB da Microsoft.

Para desregistrar um provedor UNC, use FsRtlDeregisterUncProvider e passe o parâmetro MupHandle .

Se um driver se registrar como um sistema de arquivos de disco local (chamando IoCreateDevice com o parâmetro DeviceType definido como FILE_DEVICE_DISK_FILE_SYSTEM), o driver não deverá chamar FsRtlRegisterUncProviderEx para se registrar como um provedor UNC com MUP.

Para obter mais informações, consulte as seguintes seções no Guia de Design:

Suporte para Nomenclatura UNC e MUP

Alterações de MUP no Microsoft Windows Vista

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)