Função NetUseAdd (lmuse.h)

Artigo
03/05/2024

A função NetUseAdd estabelece uma conexão entre o computador local e um servidor remoto. Você pode especificar uma letra da unidade local ou um dispositivo de impressora para se conectar. Se você não especificar uma letra da unidade local ou um dispositivo de impressora, a função autentica o cliente com o servidor para conexões futuras.

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetUseAdd(
  [in]  LPTSTR  servername,
  [in]  DWORD   LevelFlags,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

Parâmetros

[in] servername

O nome UNC do computador no qual executar essa função. Se esse parâmetro for NULL, o computador local será usado. Se o parâmetro UncServerName especificado for um computador remoto, o computador remoto deverá dar suporte a chamadas RPC remotas usando o mecanismo herdado do Protocolo de Acesso Remoto.

Essa cadeia de caracteres será Unicode se _WIN32_WINNT ou FORCE_UNICODE estiverem definidos.

[in] LevelFlags

Um valor que especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
1	Especifica informações sobre a conexão entre um dispositivo local e um recurso compartilhado. As informações incluem o tipo e status de conexão. O parâmetro Buf é um ponteiro para uma estrutura USE_INFO_1 .
2	Especifica informações sobre a conexão entre um dispositivo local e um recurso compartilhado. As informações incluem o status e o tipo de conexão e um nome de usuário e nome de domínio. O parâmetro Buf é um ponteiro para uma estrutura USE_INFO_2 .

[in] buf

Um ponteiro para o buffer que especifica os dados. O formato desses dados depende do valor do parâmetro Level . Para obter mais informações, consulte Buffers de função de gerenciamento de rede.

[out] parm_err

Um ponteiro para um valor que recebe o índice do primeiro membro da estrutura de informações com erro quando o erro ERROR_INVALID_PARAMETER é retornado. Se esse parâmetro for NULL, o índice não será retornado com erro. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado será um código de erro do sistema. Para obter uma lista de códigos de erro, consulte Códigos de erro do sistema.

Comentários

Você também pode usar as funções WNetAddConnection2 e WNetAddConnection3 para redirecionar um dispositivo local para um recurso de rede.

Nenhuma associação de grupo especial é necessária para chamar a função NetUseAdd . Essa função não pode ser executada em um servidor remoto, exceto em casos de compatibilidade de nível inferior.

Essa função se aplica somente ao cliente do Bloco de Mensagens do Servidor (Estação de Trabalho do LAN Manager). A função NetUseAdd não dá suporte a compartilhamentos DFS (Sistema de Arquivos Distribuído). Para adicionar um compartilhamento usando um provedor de rede diferente (WebDAV ou um compartilhamento DFS, por exemplo), use a função WNetAddConnection2 ou WNetAddConnection3 .

Se a função NetUseAdd retornar ERROR_INVALID_PARAMETER, você poderá usar o parâmetro ParmError para indicar o primeiro membro da estrutura de informações inválido. (A estrutura de informações começa com USE_INFO_ e seu formato é especificado pelo parâmetro Level .) A tabela a seguir lista os valores que podem ser retornados no parâmetro ParmError e no membro da estrutura correspondente que está com erro. (O prefixo ui*_ indica que o membro pode começar com vários prefixos, por exemplo, ui1_ ou ui2_.)

Constante	Valor	Membro
USE_LOCAL_PARMNUM	1	interface do usuário*_local
USE_REMOTE_PARMNUM	2	interface do usuário*_remote
USE_PASSWORD_PARMNUM	3	interface do usuário*_password
USE_ASGTYPE_PARMNUM	4	interface do usuário*_asg_type
USE_USERNAME_PARMNUM	5	interface do usuário*_username
USE_DOMAINNAME_PARMNUM	6	interface do usuário*_domainname

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	lmuse.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll