Função WNetAddConnection2A (winnetwk.h)
A função WNetAddConnection2 faz uma conexão com um recurso de rede e pode redirecionar um dispositivo local para o recurso de rede.
A função WNetAddConnection2 substitui a função WNetAddConnection . Se você puder passar um identificador para uma janela que o provedor de recursos de rede pode usar como uma janela de proprietário para caixas de diálogo, chame a função WNetAddConnection3 .
Sintaxe
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Parâmetros
[in] lpNetResource
Um ponteiro para uma estrutura NETRESOURCE que especifica detalhes da conexão proposta, como informações sobre o recurso de rede, o dispositivo local e o provedor de recursos de rede.
Você deve especificar os membros a seguir da estrutura NETRESOURCE .
A função WNetAddConnection2 ignora os outros membros da estrutura NETRESOURCE .
[in] lpPassword
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica uma senha a ser usada para fazer a conexão de rede.
Se lpPassword for NULL, a função usará a senha padrão atual associada ao usuário especificado pelo parâmetro lpUserName .
Se lpPassword apontar para uma cadeia de caracteres vazia, a função não usará uma senha.
Se a conexão falhar devido a uma senha inválida e o valor CONNECT_INTERACTIVE for definido no parâmetro dwFlags , a função exibirá uma caixa de diálogo solicitando que o usuário digite a senha.
Windows Me/98/95: Esse parâmetro deve ser NULL ou uma cadeia de caracteres vazia.
[in] lpUserName
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica um nome de usuário para fazer a conexão.
Se lpUserName for NULL, a função usará o nome de usuário padrão. (O contexto do usuário para o processo fornece o nome de usuário padrão.)
O parâmetro lpUserName é especificado quando os usuários desejam se conectar a um recurso de rede para o qual receberam um nome de usuário ou uma conta diferente do nome de usuário ou da conta padrão.
A cadeia de caracteres de nome de usuário representa um contexto de segurança. Pode ser específico para um provedor de rede.
Windows Me/98/95: Esse parâmetro deve ser NULL ou uma cadeia de caracteres vazia.
[in] dwFlags
Um conjunto de opções de conexão. Os valores possíveis para as opções de conexão são definidos no arquivo de cabeçalho Winnetwk.h . Os valores a seguir podem ser usados no momento.
| Valor | Significado |
|---|---|
|
A conexão de recurso de rede deve ser lembrada.
Se esse sinalizador de bit estiver definido, o sistema operacional tentará restaurar automaticamente a conexão quando o usuário fizer logon. O sistema operacional lembra apenas as conexões bem-sucedidas que redirecionam dispositivos locais. Ele não se lembra de conexões malsucedidas ou sem dispositivo. (Uma conexão sem dispositivo ocorre quando o membro lpLocalName é NULL ou aponta para uma cadeia de caracteres vazia.) Se esse sinalizador de bit estiver claro, o sistema operacional não tentará restaurar a conexão quando o usuário fizer logon. |
|
A conexão de recurso de rede não deve ser colocada na lista de conexões recentes.
Se esse sinalizador estiver definido e a conexão for adicionada com êxito, a conexão de recurso de rede será colocada na lista de conexões recentes somente se tiver um dispositivo local redirecionado associado a ele. |
|
A conexão de recurso de rede não deve ser lembrada.
Se esse sinalizador estiver definido, o sistema operacional não tentará restaurar a conexão quando o usuário fizer logon novamente. |
|
Se esse sinalizador for definido, o sistema operacional poderá interagir com o usuário para fins de autenticação. |
|
Esse sinalizador instrui o sistema a não usar nenhuma configuração padrão para nomes de usuário ou senhas sem oferecer ao usuário a oportunidade de fornecer uma alternativa. Esse sinalizador é ignorado, a menos que CONNECT_INTERACTIVE também esteja definido. |
|
Esse sinalizador força o redirecionamento de um dispositivo local ao fazer a conexão.
Se o membro lpLocalName de NETRESOURCE especificar um dispositivo local para redirecionar, esse sinalizador não terá efeito, pois o sistema operacional ainda tenta redirecionar o dispositivo especificado. Quando o sistema operacional escolhe automaticamente um dispositivo local, o membro dwType não deve ser igual a RESOURCETYPE_ANY. Se esse sinalizador não estiver definido, um dispositivo local será automaticamente escolhido para redirecionamento somente se a rede exigir que um dispositivo local seja redirecionado. Windows Server 2003 e Windows XP: Quando o sistema atribui automaticamente letras de unidade de rede, as letras são atribuídas começando com Z:, depois Y:, e terminando com C:. Isso reduz a colisão entre letras de unidade por logon (como letras de unidade de rede) e letras de unidade globais (como unidades de disco). Observe que versões anteriores de letras de unidade atribuídas pelo Windows começando com C: e terminando com Z:. |
|
Se esse sinalizador estiver definido, o sistema operacional não começará a usar uma nova mídia para tentar estabelecer a conexão (inicie uma nova conexão de discagem, por exemplo). |
|
Se esse sinalizador estiver definido, o sistema operacional solicitará ao usuário a autenticação usando a linha de comando em vez de uma GUI (interface gráfica do usuário). Esse sinalizador é ignorado, a menos que CONNECT_INTERACTIVE também esteja definido.
Windows XP: Esse valor tem suporte no Windows XP e posterior. |
|
Se esse sinalizador estiver definido e o sistema operacional solicitar uma credencial, a credencial deverá ser salva pelo gerenciador de credenciais. Se o gerenciador de credenciais estiver desabilitado para a sessão de logon do chamador ou se o provedor de rede não der suporte ao salvamento de credenciais, esse sinalizador será ignorado. Esse sinalizador é ignorado, a menos que CONNECT_INTERACTIVE também esteja definido. Esse sinalizador também é ignorado, a menos que você defina o sinalizador CONNECT_COMMANDLINE.
Windows XP: Esse valor tem suporte no Windows XP e posterior. |
|
Se esse sinalizador estiver definido e o sistema operacional solicitar uma credencial, a credencial será redefinida pelo gerenciador de credenciais. Se o gerenciador de credenciais estiver desabilitado para a sessão de logon do chamador ou se o provedor de rede não der suporte ao salvamento de credenciais, esse sinalizador será ignorado. Esse sinalizador também é ignorado, a menos que você defina o sinalizador CONNECT_COMMANDLINE.
Windows Vista: Esse valor tem suporte no Windows Vista e posterior. |
Valor retornado
Se a função for bem-sucedida, o valor retornado será NO_ERROR.
Se a função falhar, o valor retornado poderá ser um dos códigos de erro a seguir ou um dos códigos de erro do sistema.
| Código de retorno | Descrição |
|---|---|
|
O chamador não tem acesso ao recurso de rede. |
|
O dispositivo local especificado pelo membro lpLocalName já está conectado a um recurso de rede. |
|
O tipo de dispositivo local e o tipo de recurso de rede não correspondem. |
|
O nome do dispositivo especificado não é válido. Esse erro será retornado se o membro lpLocalName da estrutura NETRESOURCE apontado pelo parâmetro lpNetResource especificar um dispositivo que não é redirecionável. |
|
O nome de rede não foi encontrado. Esse valor será retornado se o membro lpRemoteName da estrutura NETRESOURCE apontado pelo parâmetro lpNetResource especificar um recurso que não é aceitável para nenhum provedor de recursos de rede, seja porque o nome do recurso está vazio, não válido ou porque o recurso nomeado não pode ser localizado. |
|
O perfil do usuário está em um formato incorreto. |
|
O nome do provedor de rede especificado não é válido. Esse erro será retornado se o membro lpProvider da estrutura NETRESOURCE apontado pelo parâmetro lpNetResource especificar um valor que não corresponda a nenhum provedor de rede. |
|
O nome de usuário especificado não é válido. |
|
O roteador ou provedor está ocupado, possivelmente inicializando. O chamador deve tentar novamente. |
|
A tentativa de fazer a conexão foi cancelada pelo usuário por meio de uma caixa de diálogo de um dos provedores de recursos de rede ou por um recurso chamado. |
|
O sistema não consegue abrir o perfil do usuário para processar conexões persistentes. |
|
O nome do dispositivo local tem uma conexão lembrada com outro recurso de rede. Esse erro será retornado se uma entrada para o dispositivo especificada pelo membro lpLocalName da estrutura NETRESOURCE apontada pelo parâmetro lpNetResource especificar um valor que já está no perfil do usuário para uma conexão diferente daquela especificada no parâmetro lpNetResource . |
|
Ocorreu um erro específico da rede. Chame a função WNetGetLastError para obter uma descrição do erro. |
|
Foi feita uma tentativa de acessar um endereço inválido. Esse erro será retornado se o parâmetro dwFlags especificar um valor de CONNECT_REDIRECT, mas o membro lpLocalName da estrutura NETRESOURCE apontado pelo parâmetro lpNetResource não tiver sido especificado. |
|
Um parâmetro está incorreto. Esse erro será retornado se o membro dwType da estrutura NETRESOURCE apontado pelo parâmetro lpNetResource especificar um valor diferente de RESOURCETYPE_DISK, RESOURCETYPE_PRINT ou RESOURCETYPE_ANY. Esse erro também será retornado se o parâmetro dwFlags especificar um valor incorreto ou desconhecido. |
|
A senha especificada é inválida e o sinalizador CONNECT_INTERACTIVE não está definido. |
|
Uma falha de logon devido a um nome de usuário desconhecido ou uma senha incorreta. |
|
Nenhum provedor de rede aceitou o caminho de rede fornecido. Esse erro será retornado se nenhum provedor de rede reconheceu o membro lpRemoteName da estrutura NETRESOURCE apontada pelo parâmetro lpNetResource . |
|
A rede não está disponível. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
No Windows Server 2003 e no Windows XP, as funções WNet criam e excluem letras da unidade de rede no namespace do dispositivo MS-DOS associado a uma sessão de logon porque os dispositivos MS-DOS são identificados por AuthenticationID (um
identificador local 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 . A chamada para a função GetLogicalDrives não retorna letras de unidade de rede criadas por chamadas de 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.
No Windows Server 2003 e no Windows XP, se um serviço executado como LocalSystem chamar a função WNetAddConnection2, a unidade mapeada ficará visível para todas as sessões de logon do usuário.
Para provedores de rede da Microsoft, o membro lpRemoteName da estrutura NETRESOURCE apontada pelo parâmetro lpNetResource pode conter um endereço IPv4 na notação dotted-decimal. Um exemplo para um compartilhamento pode ser o seguinte:
\192.168.1.1\share
Para provedores de rede da Microsoft no Windows Vista e posteriores, o membro lpRemoteName da estrutura NETRESOURCE apontada pelo parâmetro lpNetResource pode conter um endereço IPv6. No entanto, o formato literal IPv6 deve ser usado para que o endereço IPv6 seja analisado corretamente. Um endereço literal IPv6 é do formato:
ipv6-address com os caracteres ':' substituídos por caracteres '-' seguidos pela cadeia de caracteres ".ipv6-literal.net".
Por exemplo, para o seguinte endereço IPv6:
2001:4898:9:3:c069:aa97:fe76:2449
um exemplo para um compartilhamento pode ser o seguinte:
\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share
Outros provedores de rede podem dar suporte ao membro lpRemoteName da estrutura NETRESOURCE apontada pelo parâmetro lpNetResource que contém um endereço IPv4 ou IPv6, mas isso cabe ao provedor de rede específico.
Windows 7 e Windows Server 2008 R2: Se a função WNetAddConnection2 for chamada com credenciais de usuário explícitas especificadas no pUsername e lpPassword para estabelecer uma conexão com um recurso de rede em um servidor específico e, em seguida, chamada novamente com qualquer um desses parâmetros como NULL (para usar o nome de usuário padrão ou senha padrão) para o mesmo servidor, a chamada com falha. O erro retornado será ERROR_BAD_USERNAME ou ERROR_INVALID_PASSWORD.
Exemplos
O exemplo de código a seguir ilustra como usar a função WNetAddConnection2 para fazer conexão com 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>
// Need to link with Netapi32.lib and Mpr.lib
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
NETRESOURCE nr;
DWORD dwFlags;
if (argc != 5) {
wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
argv[0]);
wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",
argv[0]);
exit(1);
}
wprintf(L"Calling WNetAddConnection2 with\n");
wprintf(L" lpLocalName = %s\n", argv[1]);
wprintf(L" lpRemoteName = %s\n", argv[2]);
wprintf(L" lpUsername = %s\n", argv[3]);
wprintf(L" lpPassword = %s\n", argv[4]);
// Zero out the NETRESOURCE struct
memset(&nr, 0, sizeof (NETRESOURCE));
// Assign our values to the NETRESOURCE structure.
nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];
nr.lpRemoteName = argv[2];
nr.lpProvider = NULL;
// Assign a value to the connection options
dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
// a drive letter to the share.
//
dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
// print the error.
//
if (dwRetVal == NO_ERROR)
wprintf(L"Connection added to %s\n", nr.lpRemoteName);
else
wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);
exit(1);
}
Para outros exemplos de código que ilustram como fazer uma conexão com um recurso de rede usando a função WNetAddConnection2 , consulte Adicionando uma conexão de rede e Atribuindo uma unidade a um compartilhamento.
Observação
O cabeçalho winnetwk.h define WNetAddConnection2 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 |