Função WNetAddConnectionA (winnetwk.h)

Artigo
11/20/2024

A função WNetAddConnection permite que o aplicativo de chamada conecte um dispositivo local a um recurso de rede. Uma conexão bem-sucedida é persistente, o que significa que o sistema restaura automaticamente a conexão durante as operações de logon subsequentes.

Observação Essa função é fornecida apenas para compatibilidade com versões de 16 bits do Windows. Outros aplicativos baseados no Windows devem chamar o WNetAddConnection2 ou a função WNetAddConnection3.

Sintaxe

DWORD WNetAddConnectionA(
  [in] LPCSTR lpRemoteName,
  [in] LPCSTR lpPassword,
  [in] LPCSTR lpLocalName
);

Parâmetros

[in] lpRemoteName

Um ponteiro para uma constante cadeia de caracteresterminada nula que especifica o recurso de rede ao qual se conectar.

[in] lpPassword

Um ponteiro para uma constante cadeia de caracteresterminada nula que especifica a senha a ser usada para fazer uma conexão. Esse parâmetro geralmente é a senha associada ao usuário atual.

Se esse parâmetro for NULL, a senha padrão será usada. Se a cadeia de caracteres estiver vazia, nenhuma senha será usada.

Windows Me/98/95: Esse parâmetro deve ser NULL ou uma cadeia de caracteres vazia.

[in] lpLocalName

Um ponteiro para uma constante cadeia de caracteres nulaterminada 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 for NULL, uma conexão com o recurso de rede será feita sem redirecionar o dispositivo local.

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
ERROR_ACCESS_DENIED	O chamador não tem acesso ao recurso de rede.
ERROR_ALREADY_ASSIGNED	O dispositivo especificado no parâmetro lpLocalName já está conectado.
ERROR_BAD_DEV_TYPE	O tipo de dispositivo e o tipo de recurso não correspondem.
ERROR_BAD_DEVICE	O valor especificado no parâmetro lpLocalName é inválido.
ERROR_BAD_NET_NAME	O valor especificado no parâmetro lpRemoteName não é válido ou não pode ser localizado.
ERROR_BAD_PROFILE	O perfil do usuário está em um formato incorreto.
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 no parâmetro lpLocalName já está no perfil do usuário.
ERROR_EXTENDED_ERROR	Ocorreu um erro específico da rede. Para obter uma descrição do erro, chame a função WNetGetLastError.
ERROR_INVALID_PASSWORD	A senha especificada é inválida.
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.

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 WNetAddConnection, a unidade mapeada ficará visível para todas as sessões de logon do usuário.

Nota

O cabeçalho winnetwk.h define WNetAddConnection 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

WNetAddConnection2

WNetAddConnection3

WNetCancelConnection

WNetCancelConnection2

WNetGetConnection

Visão geral WNet (Rede windows)

funções de rede do Windows

Compartilhar via