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 é semelhante à função WNetAddConnection2 . A main diferença é que WNetAddConnection3 tem um parâmetro adicional, 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. A função WNetAddConnection2 e a função WNetAddConnection3 substituem a função WNetAddConnection .
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 hwndOwner pode ser NULL. Se for, uma chamada para WNetAddConnection3 será equivalente a chamar a função WNetAddConnection2 .
[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 WNetAddConnection3 ignora os outros membros da estrutura NETRESOURCE .
[in] lpPassword
Um ponteiro para uma cadeia de caracteres terminada em nulo 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 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 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 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:. |
|
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 quando aponta para uma cadeia de caracteres vazia.) Se esse sinalizador de bit 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 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 2000/NT e Windows Me/98/95: Não há suporte para esse valor. |
Retornar valor
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 membro lpRemoteName não é aceitável para nenhum 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 não corresponde a nenhum provedor. |
|
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 WNetGetLastError para obter uma descrição do erro. |
|
A senha especificada é inválida e o sinalizador 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. |
Comentários
A função WNetUseConnection é semelhante à função WNetAddConnection3 . A main diferença é que o WNetUseConnection pode selecionar automaticamente um dispositivo local não utilizado para redirecionar para o recurso de rede.
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 os dispositivos MS-DOS são identificados por AuthenticationID (um
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 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 WNetAddConnection3, 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 formulário:
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 WNetAddConnection3 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.
Observação
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. 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
| Requisito | Valor |
|---|---|
| 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 |