IOCTL_REDIR_QUERY_PATH IOCTL (ntifs.h)

Artigo
10/14/2023

O código de controle IOCTL_REDIR_QUERY_PATH é enviado pelo MUP (provedor UNC múltiplo) 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 é conhecida como "resolução de prefixo".

O MUP é um componente do modo kernel responsável por canalizar todos os acessos remotos do sistema de arquivos que usam 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 redirecionador de rede no modo kernel durante essa operação.

No Windows Server 2003, Windows XP e Windows 2000, as operações de arquivo remoto executadas em uma unidade mapeada que não representa uma unidade dfs (Sistema de Arquivos Distribuído) não passam pelo MUP. Essas operações vão diretamente para o provedor de rede que lidou com o mapeamento de letras da unidade.

Para redirecionadores de rede que estão em conformidade com o modelo de redirecionador 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 por MUP para 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 é enviado para redirecionadores de rede que se registraram no MUP como provedores UNC (Convenção Universal de Nomenclatura) chamando FsRtlRegisterUncProvider. Pode haver vários provedores UNC registrados no MUP.

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

A operação baseada em nome que resultou na resolução do prefixo é roteada para o provedor que reivindica o prefixo. Se tiver êxito, o MUP garantirá que as operações subsequentes baseadas em identificador (IRP_MJ_READ e IRP_MJ_WRITE, por exemplo) vão para o mesmo provedor ignorando completamente o MUP.
O provedor e o prefixo que ele alegou são inseridos em um cache de prefixo que é 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 de ser adicionado ao cache. Uma entrada é descartada depois que esse tempo limite expira, quando 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

Buffer de entrada

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

Comprimento do buffer de entrada

Comprimento do buffer de entrada, em bytes, que deve ser pelo menos sizeof(QUERY_PATH_REQUEST).

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

Comprimento do buffer de saída, em bytes, que deve ser pelo menos sizeof(QUERY_PATH_RESPONSE).

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 (\\servidor, 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 (\\servidor, 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 de 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 falhar 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 devem respeitar apenas os remetentes do modo kernel desse IOCTL, verificando se Irp-RequestorMode> é KernelMode.

Observe que IOCTL_REDIR_QUERY_PATH é 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 os mesmos e usar o ponteiro do buffer de entrada para fornecer a resposta.

Quando um provedor UNC recebe uma solicitação IOCTL_REDIR_QUERY_PATH, ele precisa determinar se ele pode manipular o caminho UNC especificado no membro FilePathName da estrutura QUERY_PATH_REQUEST . Nesse caso, ele 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 manipular o caminho UNC especificado, ele deverá falhar na solicitação de IOCTL_REDIR_QUERY_PATH com um código de erro NTSTATUS apropriado e não deverá atualizar o membro LengthAccepted da estrutura QUERY_PATH_RESPONSE . Os provedores não devem modificar nenhum dos outros membros ou a cadeia de caracteres FilePathName em 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 \\server\marketing\presentation 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: