Função WNetAddConnection3A (winnetwk.h)
A função WNetAddConnection3 faz uma conexão com um recurso de rede. A função pode redirecionar um dispositivo local para o recurso de rede.
A função WNetAddConnection3
Sintaxe
DWORD WNetAddConnection3A(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Parâmetros
[in] hwndOwner
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. Use esse parâmetro se você definir o valor CONNECT_INTERACTIVE no parâmetro dwFlags.
O parâmetro
[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 um cadeia de caracteresterminada nula 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 um 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 a seguir estão definidos no momento.
| Valor | Significado |
|---|---|
|
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:. |
|
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 quando aponta para uma cadeia de caracteres vazia.) Se esse sinalizador de bits estiver claro, o sistema operacional não restaurará automaticamente a conexão no logon. |
|
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 2000/NT e Windows Me/98/95: Não há suporte para esse valor. |
|
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 também é ignorado, a menos que você defina o sinalizador de CONNECT_COMMANDLINE.
Windows 2000/NT e Windows Me/98/95: Não há suporte para esse valor. |
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 |
|---|---|
|
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 valor especificado por lpLocalName é inválido. |
|
O valor especificado pelo lpRemoteName membro não é aceitável para qualquer provedor de recursos de rede, seja porque o nome do recurso é inválido ou porque o recurso nomeado não pode ser localizado. |
|
O perfil do usuário está em um formato incorreto. |
|
O valor especificado pelo membro lpProvider |
|
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. |
|
Uma entrada para o dispositivo especificado pelo membro lpLocalName já está no perfil do usuário. |
|
Ocorreu um erro específico da rede. Chame a função |
|
A senha especificada é inválida e o sinalizador de CONNECT_INTERACTIVE não está definido. |
|
A operação não pode ser executada porque um componente de rede não foi iniciado ou porque um nome especificado não pode ser usado. |
|
A rede não está disponível. |
Observações
A função WNetUseConnection
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 WNetAddConnection3, 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
Windows 7 e Windows Server 2008 R2: se a função WNetAddConnection3 for chamada com credenciais de usuário explícitas especificadas no pUsername e lpPassword estabelecer uma conexão com um recurso de rede em um servidor específico e, em seguida, chamado 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.
Nota
O cabeçalho winnetwk.h define WNetAddConnection3 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. 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
WNetAddConnection2
Visão geral WNet (Rede windows)