Função WNetGetUniversalNameA (winnetwk.h)

Artigo
03/08/2023

A função WNetGetUniversalName usa um caminho baseado em unidade para um recurso de rede e retorna uma estrutura de informações que contém uma forma mais universal do nome.

Sintaxe

DWORD WNetGetUniversalNameA(
  [in]      LPCSTR  lpLocalPath,
  [in]      DWORD   dwInfoLevel,
  [out]     LPVOID  lpBuffer,
  [in, out] LPDWORD lpBufferSize
);

Parâmetros

[in] lpLocalPath

Um ponteiro para uma cadeia de caracteres terminada em nulo constante que é um caminho baseado em unidade para um recurso de rede.

Por exemplo, se a unidade H tiver sido mapeada para um compartilhamento de unidade de rede e o recurso de rede de interesse for um arquivo chamado Sample.doc no diretório \Win32\Examples nesse compartilhamento, o caminho baseado em unidade será H:\Win32\Examples\Sample.doc.

[in] dwInfoLevel

O tipo de estrutura que a função armazena no buffer apontado pelo parâmetro lpBuffer. Esse parâmetro pode ser um dos seguintes valores definidos no arquivo de cabeçalho Winnetwk.h.

Valor	Significado
UNIVERSAL_NAME_INFO_LEVEL	A função armazena uma estrutura UNIVERSAL_NAME_INFO no buffer.
REMOTE_NAME_INFO_LEVEL	A função armazena uma estrutura REMOTE_NAME_INFO no buffer.

A estrutura UNIVERSAL_NAME_INFO aponta para uma cadeia de caracteres de nome UNC (Convenção Universal de Nomenclatura).

A estrutura REMOTE_NAME_INFO aponta para uma cadeia de caracteres de nome UNC e duas cadeias de caracteres de informações de conexão adicionais. Para obter mais informações, consulte a seção Comentários a seguir.

[out] lpBuffer

Um ponteiro para um buffer que recebe a estrutura especificada pelo parâmetro dwInfoLevel .

[in, out] lpBufferSize

Um ponteiro para uma variável que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro lpBuffer.

Se a função for bem-sucedida, ela definirá a variável apontada por lpBufferSize para o número de bytes armazenados no buffer. Se a função falhar porque o buffer é muito pequeno, esse local recebe o tamanho do buffer necessário e a função retorna ERROR_MORE_DATA.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um código de erro do sistema, como um dos valores a seguir.

Código de retorno	Descrição
ERROR_BAD_DEVICE	A cadeia de caracteres apontada pelo parâmetro lpLocalPath é inválida.
ERROR_CONNECTION_UNAVAIL	Não há nenhuma conexão atual com o dispositivo remoto, mas há uma conexão lembrada (persistente) com ele.
ERROR_EXTENDED_ERROR	Ocorreu um erro específico da rede. Use a função WNetGetLastError para obter uma descrição do erro.
ERROR_MORE_DATA	O buffer apontado pelo parâmetro lpBuffer é muito pequeno. A função define a variável apontada pelo parâmetro lpBufferSize para o tamanho do buffer necessário. Mais entradas estão disponíveis com chamadas subsequentes.
ERROR_NOT_SUPPORTED	O parâmetro dwInfoLevel está definido como UNIVERSAL_NAME_INFO_LEVEL, mas o provedor de rede não dá suporte a nomes UNC. (Nenhum dos provedores de rede dá suporte a essa função.)
ERROR_NO_NET_OR_BAD_PATH	Nenhum dos provedores de rede reconhece o nome local como tendo uma conexão. No entanto, a rede não está disponível para pelo menos um provedor ao qual a conexão pode pertencer.
ERROR_NO_NETWORK	A rede não está disponível.
ERROR_NOT_CONNECTED	O dispositivo especificado pelo parâmetro lpLocalPath não é redirecionado.

Observações

Uma forma universal de um caminho baseado em unidade local identifica um recurso de rede de maneira inequívoca e independente de computador. Em seguida, o nome pode ser passado para processos em outros computadores, permitindo que esses processos obtenham acesso ao recurso.

A função WNetGetUniversalName atualmente dá suporte a um formulário de nome universal: nomes UNC (convenção de nomenclatura universal), que se parecem com o seguinte:

\\servername\sharename\path\file

Usando o exemplo da descrição anterior do parâmetro lpLocalPath, se a unidade de rede compartilhada estiver em um servidor chamado COOLSERVER e o nome do compartilhamento for HOTSHARE, o nome UNC do recurso de rede cujo nome baseado em unidade é H:\Win32\Examples\Sample.doc seria o seguinte:

\\coolserver\hotshare\win32\examples\sample.doc

A estrutura UNIVERSAL_NAME_INFO contém um ponteiro para uma cadeia de caracteres de nome UNC. A estrutura REMOTE_NAME_INFO também contém um ponteiro para uma cadeia de caracteres de nome UNC, bem como ponteiros para duas outras cadeias de caracteres úteis. Por exemplo, um processo pode passar o membro lpszConnectionInfo da estrutura REMOTE_NAME_INFO para a função WNetAddConnection2 para conectar um dispositivo local ao recurso de rede. Em seguida, o processo pode acrescentar a cadeia de caracteres apontada pelo membro lpszRemainingPath à cadeia de caracteres do dispositivo local. A cadeia de caracteres resultante pode ser passada para funções que exigem um caminho baseado em unidade.

O parâmetro lpLocalPath não precisa especificar um caminho ou recurso que já esteja presente em um recurso remoto. Por exemplo, o parâmetro lpLocalPath pode especificar e pasta, uma hierarquia de pastas ou um arquivo que não existe no momento. A função WNetGetUniversalName retorna uma forma mais universal do nome nesses casos.

O tamanho do buffer apontado pelo parâmetro lpBuffer e especificado no parâmetro lpBufferSize deve ser muito maior do que o tamanho das estruturas REMOTE_NAME_INFO ou UNIVERSAL_NAME_INFO. O buffer apontado pelo parâmetro lpBuffer deve ser grande o suficiente para armazenar as cadeias de caracteres UNC apontadas pelos membros nas estruturas REMOTE_NAME_INFO ou UNIVERSAL_NAME_INFO. Se o tamanho do buffer for muito pequeno, a função falhará com ERROR_MORE_DATA e a variável apontada pelo parâmetro lpBufferSize indicará o tamanho do buffer necessário.

Windows Server 2003 e Windows XP: Essa função consulta os namespaces do dispositivo MS-DOS associados a uma sessão de logon porque MS-DOS dispositivos são identificados pela AuthenticationID. (Uma AuthenticationID é o identificador localmente exclusivo, ou LUID, associado a uma sessão de logon.) Isso pode afetar aplicativos que chamam uma das funções WNet para criar uma letra de unidade de rede em um logon de usuário, mas consultam letras de unidade de rede existentes em um logon de usuário diferente. Um exemplo dessa situação pode ser quando o segundo logon de um usuário é criado em uma sessão de logon, por exemplo, chamando a função CreateProcessAsUser e o segundo logon executa um aplicativo que chama a função GetLogicalDrives. GetLogicalDrives não retorna letras de unidade de rede criadas por uma função WNet no primeiro logon. Observe que, no exemplo anterior, a primeira sessão de logon ainda existe e o exemplo pode ser aplicado a qualquer sessão de logon, incluindo uma sessão dos Serviços de Terminal. Para obter mais informações, consulte Definindo umde nome do dispositivo MS-DOS.

Exemplos

O exemplo de código a seguir ilustra como usar a função WNetGetUniversalName para recuperar as cadeias de caracteres de nome UNC universais associadas ao caminho baseado em unidade para um recurso de rede.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])
{
    DWORD dwRetVal;

    WCHAR Buffer[1024];
    DWORD dwBufferLength = 1024;
       
    UNIVERSAL_NAME_INFO * unameinfo;
    REMOTE_NAME_INFO *remotenameinfo;
    
    wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);

    unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }


    remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL, 
        (LPVOID) remotenameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
        wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
        wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }
}

Nota

O cabeçalho winnetwk.h define WNetGetUniversalName como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winnetwk.h
biblioteca	Mpr.lib
de DLL	Mpr.dll