IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Artigo
10/10/2023

A partir do Windows Vista, o MUP (vários provedores UNC) envia um código de controle IOCTL_REDIR_QUERY_PATH_EX para redirecionadores de rede para determinar qual provedor pode lidar com um caminho UNC específico em uma operação baseada em nome, normalmente uma solicitação de IRP_MJ_CREATE. Essa solicitação é chamada de "resolução de prefixo".

O MUP é um componente do modo kernel responsável por canalizar todos os acessos remotos do sistema de arquivos usando um nome UNC para um redirecionador de rede (o provedor UNC) capaz de lidar com as solicitações remotas do sistema de arquivos. O MUP está envolvido quando um caminho UNC é usado conforme ilustrado pelo exemplo a seguir que pode ser executado 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.

O código de controle IOCTL_REDIR_QUERY_PATH_EX é enviado para redirecionadores de rede que se registraram no MUP como provedores UNC (Convenção Universal de Nomenclatura) chamando FsRtlRegisterUncProviderEx. Pode haver vários provedores UNC registrados no MUP.

A operação de resolução de prefixo serve a duas finalidades:

A operação baseada em nome que resultou na resolução de prefixo é roteada para o provedor que reivindica o prefixo. Se tiver êxito, o MUP garante que as operações subsequentes baseadas em identificador (IRP_MJ_READ e IRP_MJ_WRITE, por exemplo) passem pelo MUP para o mesmo provedor. Observe que esse comportamento é diferente para redirecionadores de rede que não estão em conformidade com o modelo de redirecionamento do Windows Vista, que será enviado IOCTL_REDIR_QUERY_PATH para resolução de prefixo. Para redirecionadores de rede que não estão em conformidade com o modelo de redirecionamento do Windows Vista, o MUP é completamente ignorado para operações baseadas em identificador subsequentes.
O provedor e o prefixo que ele alegou são inseridos em um cache de prefixo mantido pelo MUP. Para operações baseadas em nome subsequentes, o MUP usa esse cache de prefixo para determinar se um provedor já reivindicou um prefixo antes que o MUP tente executar uma resolução de prefixo. Cada entrada nesse cache de prefixo está sujeita a um tempo limite (conhecido como TTL) depois que ele é adicionado ao cache. Uma entrada é descartada após esse tempo limite expirar, momento em que o MUP executará a resolução de prefixo novamente para esse prefixo em uma operação baseada em nome subsequente.

Código principal

IOCTL_REDIR_QUERY_PATH_EX

Buffer de entrada

IrpSp->Parameters.DeviceIoControl.Type3InputBuffer é definido como uma estrutura de dados QUERY_PATH_REQUEST_EX que contém a solicitação.

Comprimento do buffer de entrada

Tamanho da estrutura QUERY_PATH_REQUEST_EX para a qual o buffer de entrada aponta, em bytes.

Buffer de saída

IRP->UserBuffer é definido como uma estrutura de dados QUERY_PATH_RESPONSE que contém a resposta.

Comprimento do buffer de saída

O tamanho da estrutura QUERY_PATH_RESPONSE para a qual o buffer de saída aponta, em bytes.

Buffer de entrada/saída

n/d

Comprimento do buffer de entrada/saída

n/d

Bloco de status

O membro Status será definido como STATUS_SUCCESS com êxito se o nome do prefixo \\server\share for reconhecido ou para um valor NTSTATUS apropriado, como um dos seguintes:

Código de status	Significado
STATUS_BAD_NETWORK_NAME	O nome do compartilhamento especificado não pode ser encontrado no servidor remoto. O nome do computador (\\server, por exemplo) é válido, mas o nome do compartilhamento especificado não pode ser encontrado no servidor remoto.
STATUS_BAD_NETWORK_PATH	O caminho de rede não pode ser localizado. O nome do computador (\\server, por exemplo) não é válido ou o redirecionador de rede não pode resolve o nome do computador (usando os mecanismos de resolução de nomes disponíveis).
STATUS_INSUFFICIENT_RESOURCES	Não havia recursos suficientes disponíveis para alocar memória para buffers.
STATUS_INVALID_DEVICE_REQUEST	Uma solicitação IOCTL_REDIR_QUERY_PATH_EX só deve vir do MUP e o membro RequestorMode da estrutura IRP sempre deve ser KernelMode. Esse código de erro será retornado se o modo solicitante do thread de chamada não for KernelMode.
STATUS_INVALID_PARAMETER	O membro PathNameLength na estrutura QUERY_PATH_REQUEST excede o comprimento máximo permitido, UNICODE_STRING_MAX_BYTES, para uma cadeia de caracteres Unicode.
STATUS_LOGON_FAILURE ou STATUS_ACCESS_DENIED	Se a operação de resolução de prefixo falhou devido a credenciais inválidas ou incorretas, o provedor deverá retornar o código de erro exato retornado pelo servidor remoto; esses códigos de erro não devem ser convertidos em STATUS_BAD_NETWORK_NAME ou STATUS_BAD_NETWORK_PATH. Códigos de erro como STATUS_LOGON_FAILURE e STATUS_ACCESS_DENIED servem como um mecanismo de comentários para o usuário e indicam o requisito de usar as credenciais apropriadas. Esses códigos de erro também são usados em determinados casos para solicitar credenciais automaticamente ao usuário. Sem esses códigos de erro, o usuário pode assumir que o computador não está acessível.

Se o redirecionador de rede não puder resolve um prefixo, ele deverá retornar um código NTSTATUS que corresponda de perto à semântica pretendida da lista acima de códigos NTSTATUS recomendados. Um redirecionador de rede não deve retornar o erro real encontrado (STATUS_CONNECTION_REFUSED, por exemplo) diretamente para MUP se o código NTSTATUS não for da lista acima.

Comentários

Os redirecionadores de rede só devem respeitar os remetentes do modo kernel deste IOCTL, verificando se Irp-RequestorMode> é KernelMode.

Observe que IOCTL_REDIR_QUERY_PATH_EX é um IOCTL METHOD_NEITHER. Isso significa que os buffers de entrada e saída podem não estar no mesmo endereço. Um erro comum dos provedores UNC é assumir que o buffer de entrada e o buffer de saída são iguais e usar o ponteiro do buffer de entrada para fornecer a resposta.

Quando um provedor UNC recebe uma solicitação IOCTL_REDIR_QUERY_PATH_EX, ele precisa determinar se ele pode lidar com o caminho UNC especificado no membro PathName da estrutura QUERY_PATH_REQUEST_EX . Nesse caso, o provedor UNC precisa atualizar o membro LengthAccepted da estrutura QUERY_PATH_RESPONSE com o comprimento, em bytes, do prefixo que ele reivindicou e concluir o IRP com STATUS_SUCCESS. Se o provedor não puder lidar com o caminho UNC especificado, ele deverá falhar na solicitação IOCTL_REDIR_QUERY_PATH_EX com um código de erro NTSTATUS apropriado e não deve atualizar o membro LengthAccepted da estrutura QUERY_PATH_RESPONSE . Os provedores não devem modificar nenhum outro membro ou o membro PathName sob nenhuma condição.

O comprimento do prefixo reivindicado pelo provedor depende de um provedor UNC individual. A maioria dos provedores geralmente reivindica a parte \\servername\sharename de um caminho do formulário \\servername\sharename\path. Por exemplo, se um provedor reivindicou \\server\public dado um caminho \\server\public\dir1\dir2, todas as operações baseadas em nome para o prefixo \\server\public (\\server\public\file1, por exemplo) serão roteadas para esse provedor automaticamente sem qualquer resolução de prefixo porque o prefixo já está no cache de prefixo. No entanto, um caminho com o prefixo \\apresentação demarketing\do servidor\ passará pela resolução de prefixo.

Se um redirecionador de rede reivindicar um nome de servidor (\\servidor, por exemplo), todas as solicitações de compartilhamentos neste servidor irão para esse redirecionador de rede. Esse comportamento só será aceitável se não houver nenhuma possibilidade de outro compartilhamento no mesmo servidor ser acessado por um redirecionador de rede diferente. Por exemplo, um redirecionador de rede que declara \\server de um caminho UNC impedirá o acesso de outros redirecionadores de rede a outros compartilhamentos neste servidor (acesso WebDAV a \\server\Web, por exemplo).

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