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 .

Membro Significado
Dwtype
O tipo de recurso de rede ao qual se conectar.

Se o membro lpLocalName apontar para uma cadeia de caracteres nãompty, esse membro poderá ser igual a RESOURCETYPE_DISK ou RESOURCETYPE_PRINT.

Se lpLocalName for NULL ou se apontar para uma cadeia de caracteres vazia, dwType poderá ser igual a RESOURCETYPE_DISK, RESOURCETYPE_PRINT ou RESOURCETYPE_ANY.

Embora esse membro seja necessário, suas informações podem ser ignoradas pelo provedor de serviços de rede.

Lplocalname
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome de um dispositivo local a ser redirecionado, como "F:" ou "LPT1". A cadeia de caracteres é tratada de maneira que não diferencia maiúsculas de minúsculas.

Se a cadeia de caracteres estiver vazia ou se lpLocalName for NULL, a função fará uma conexão com o recurso de rede sem redirecionar um dispositivo local.

Lpremotename
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o recurso de rede ao qual se conectar. A cadeia de caracteres pode ter até MAX_PATH caracteres de comprimento e deve seguir as convenções de nomenclatura do provedor de rede.
lpProvider
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o provedor de rede ao qual se conectar.

Se lpProvider for NULL ou se apontar para uma cadeia de caracteres vazia, o sistema operacional tentará determinar o provedor correto analisando a cadeia de caracteres apontada pelo membro lpRemoteName .

Se esse membro não for NULL, o sistema operacional tentará fazer uma conexão somente com o provedor de rede nomeado.

Você deve definir esse membro somente se souber qual provedor de rede deseja usar. Caso contrário, permita que o sistema operacional determine para qual provedor de rede o nome de rede mapeia.

 

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
CONNECT_INTERACTIVE
Se esse sinalizador for definido, o sistema operacional poderá interagir com o usuário para fins de autenticação.
CONNECT_PROMPT
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.
CONNECT_REDIRECT
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:.

CONNECT_UPDATE_PROFILE
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.

CONNECT_COMMANDLINE
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.

CONNECT_CMD_SAVECRED
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
ERROR_ACCESS_DENIED
O chamador não tem acesso ao recurso de rede.
ERROR_ALREADY_ASSIGNED
O dispositivo local especificado pelo membro lpLocalName já está conectado a um recurso de rede.
ERROR_BAD_DEV_TYPE
O tipo de dispositivo local e o tipo de recurso de rede não correspondem.
ERROR_BAD_DEVICE
O valor especificado por lpLocalName é inválido.
ERROR_BAD_NET_NAME
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.
ERROR_BAD_PROFILE
O perfil do usuário está em um formato incorreto.
ERROR_BAD_PROVIDER
O valor especificado pelo membro lpProvider não corresponde a nenhum provedor.
ERROR_BUSY
O roteador ou provedor está ocupado, possivelmente inicializando. O chamador deve tentar novamente.
ERROR_CANCELLED
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.
ERROR_CANNOT_OPEN_PROFILE
O sistema não consegue abrir o perfil do usuário para processar conexões persistentes.
ERROR_DEVICE_ALREADY_REMEMBERED
Uma entrada para o dispositivo especificado pelo membro lpLocalName já está no perfil do usuário.
ERROR_EXTENDED_ERROR
Ocorreu um erro específico da rede. Chame a função WNetGetLastError para obter uma descrição do erro.
ERROR_INVALID_PASSWORD
A senha especificada é inválida e o sinalizador CONNECT_INTERACTIVE não está definido.
ERROR_NO_NET_OR_BAD_PATH
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.
ERROR_NO_NETWORK
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

Confira também

NETRESOURCE

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

WNetUseConnection

Visão geral da Rede do Windows (WNet)

Funções de rede do Windows