Função WNetGetUniversalNameA (winnetwk.h)
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 |
|---|---|
|
A função armazena uma estrutura UNIVERSAL_NAME_INFO no buffer. |
|
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 de Nomenclatura Universal).
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 como o número de bytes armazenados no buffer. Se a função falhar porque o buffer é muito pequeno, esse local receberá o tamanho do buffer necessário e a função retornará ERROR_MORE_DATA.
Valor retornado
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 |
|---|---|
|
A cadeia de caracteres apontada pelo parâmetro lpLocalPath é inválida. |
|
Não há nenhuma conexão atual com o dispositivo remoto, mas há uma conexão (persistente) lembrada com ele. |
|
Ocorreu um erro específico da rede. Use a função WNetGetLastError para obter uma descrição do erro. |
|
O buffer apontado pelo parâmetro lpBuffer é muito pequeno. A função define a variável apontada pelo parâmetro lpBufferSize como o tamanho do buffer necessário. Mais entradas estão disponíveis com chamadas subsequentes. |
|
O parâmetro dwInfoLevel é 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.) |
|
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. |
|
A rede não está disponível. |
|
O dispositivo especificado pelo parâmetro lpLocalPath não é redirecionado. |
Comentários
Uma forma universal de um caminho baseado em unidade local identifica um recurso de rede de maneira inequívoca e independente do 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 de dispositivo MS-DOS associados a uma sessão de logon porque os dispositivos MS-DOS são identificados por 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 se aplicar a qualquer sessão de logon, incluindo uma sessão dos Serviços de Terminal. Para obter mais informações, consulte Definindo um nome de 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);
}
}
Observação
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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winnetwk.h |
| Biblioteca | Mpr.lib |
| DLL | Mpr.dll |
Confira também
Determinando a localização de um compartilhamento
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de