Função WNetAddConnection2A (winnetwk.h)
A função
A função WNetAddConnection2
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 seguintes membros da estrutura de
A função
[in] lpPassword
Um ponteiro para uma constante cadeia de caracteres nulaterminada 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
Windows Me/98/95: Esse parâmetro deve ser NULL ou uma cadeia de caracteres vazia.
[in] lpUserName
Um ponteiro para uma constante cadeia de caracteresterminada nula 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 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 bits estiver definido, o sistema operacional tentará restaurar automaticamente a conexão quando o usuário fizer logon. O sistema operacional se lembra apenas de conexões bem-sucedidas que redirecionam dispositivos locais. Ele não se lembra de conexões que não têm êxito ou conexões 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 bits 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 recente.
Se esse sinalizador for definido e a conexão for adicionada com êxito, a conexão de recurso de rede será colocada na lista de conexões recente 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 lpLocalName membro do 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 a partir de Z:, Y:, e termina com C:. Isso reduz a colisão entre letras de unidade por logon (como letras de unidade de rede) e letras de unidade de rede globais (como unidades de disco). Observe que as versões anteriores das letras da unidade atribuídas pelo Windows começam com C: e terminam 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 oferecer 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 de 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 oferecer suporte ao salvamento de credenciais, esse sinalizador será ignorado. Esse sinalizador também é ignorado, a menos que você defina o sinalizador de CONNECT_COMMANDLINE.
Windows Vista: Esse valor tem suporte no Windows Vista e posteriores. |
Valor de retorno
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 seguintes códigos de erro 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 lpLocalName membro da estrutura NETRESOURCE apontada pelo parâmetro lpNetResource especificar um dispositivo que não é redirecionável. |
|
O nome da rede não pode ser encontrado. Esse valor será retornado se o lpRemoteName membro da estrutura NETRESOURCE apontada 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 |
|
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 por |
|
Ocorreu um erro específico da rede. Chame a função |
|
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 lpLocalName membro da estrutura NETRESOURCE apontado pelo parâmetro lpNetResource não foi especificado. |
|
Um parâmetro está incorreto. Esse erro será retornado se o |
|
A senha especificada é inválida e o sinalizador de 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 |
|
A rede não está disponível. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Observações
No Windows Server 2003 e no Windows XP, as funções WNet criam e excluem letras de unidade de rede no namespace do dispositivo MS-DOS associado a uma sessão de logon porque MS-DOS dispositivos são identificados pela AuthenticationID (a
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. 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 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.
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
\192.168.1.1\share
Para provedores de rede da Microsoft no Windows Vista e posteriores, o
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
Exemplos
O exemplo de código a seguir ilustra como usar a função
#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 obter outros exemplos de código que ilustram como fazer uma conexão com um recurso de rede usando a função
Nota
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 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 |
Consulte também
Visão geral WNet (Rede windows)