Função WNetUseConnectionW (winnetwk.h)
A função WNetUseConnection faz uma conexão com um recurso de rede. A função pode redirecionar um dispositivo local para um recurso de rede.
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.
Sintaxe
DWORD WNetUseConnectionW(
[in] HWND hwndOwner,
[in] LPNETRESOURCEW lpNetResource,
[in] LPCWSTR lpPassword,
[in] LPCWSTR lpUserId,
[in] DWORD dwFlags,
[out] LPWSTR lpAccessName,
[in, out] LPDWORD lpBufferSize,
[out] LPDWORD lpResult
);
Parâmetros
[in] hwndOwner
Manipule 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 .
[in] lpNetResource
Ponteiro para uma estrutura NETRESOURCE que especifica detalhes da conexão proposta. A estrutura contém 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 WNetUseConnection ignora os outros membros da estrutura NETRESOURCE . Para obter mais informações, consulte as descrições a seguir para o parâmetro dwFlags .
[in] lpPassword
Ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica uma senha a ser usada na conexão de rede.
Se lpPassword for NULL, a função usará a senha padrão atual associada ao usuário especificado por lpUserID.
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.
[in] lpUserId
Ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica um nome de usuário para fazer a conexão.
Se lpUserID 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 lpUserID é 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.
[in] dwFlags
Conjunto de sinalizadores de bits que descrevem a conexão. Esse parâmetro pode ser qualquer combinação dos valores a seguir.
| 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 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 atribuídas letras de unidade começando com C: e terminando com Z:. |
|
Esse sinalizador instrui o sistema operacional a armazenar a conexão de recurso de rede.
Se esse sinalizador de bit estiver definido, o sistema operacional tentará restaurar automaticamente a conexão quando o usuário fizer logon. O sistema se lembra apenas de 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 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. |
[out] lpAccessName
Ponteiro para um buffer que recebe solicitações do sistema na conexão. Este parâmetro pode ser NULL.
Se esse parâmetro for especificado e o membro lpLocalName da estrutura NETRESOURCE especificar um dispositivo local, esse buffer receberá o nome do dispositivo local. Se lpLocalName não especificar um dispositivo e a rede exigir um redirecionamento de dispositivo local ou se o valor CONNECT_REDIRECT estiver definido, esse buffer receberá o nome do dispositivo local redirecionado.
Caso contrário, o nome copiado para o buffer é o de um recurso remoto. Se especificado, esse buffer deve ser pelo menos tão grande quanto a cadeia de caracteres apontada pelo membro lpRemoteName .
[in, out] lpBufferSize
Ponteiro para uma variável que especifica o tamanho do buffer lpAccessName , em caracteres. Se a chamada falhar porque o buffer não é grande o suficiente, a função retornará o tamanho do buffer necessário nesse local. Para obter mais informações, consulte as descrições do parâmetro lpAccessName e o código de erro ERROR_MORE_DATA na seção Valores Retornados.
[out] lpResult
Ponteiro para uma variável que recebe informações adicionais sobre a conexão. Esse parâmetro pode ser o valor a seguir.
Valor retornado
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 valor especificado por lpLocalName é inválido. |
|
O valor especificado pelo membro lpRemoteName não é aceitável para nenhum provedor de recursos de rede porque o nome do recurso é inválido ou porque o recurso nomeado não pode ser localizado. |
|
O valor especificado pelo membro lpProvider não corresponde a nenhum provedor. |
|
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. |
|
Ocorreu um erro específico da rede. Para obter uma descrição do erro, chame a função WNetGetLastError . |
|
O chamador passou um ponteiro para um buffer que não pôde ser acessado. |
|
Esse erro é resultado de uma das seguintes condições:
|
|
A senha especificada é inválida e o sinalizador CONNECT_INTERACTIVE não está definido. |
|
O buffer lpAccessName é muito pequeno.
Se um dispositivo local for redirecionado, o buffer precisará ser grande o suficiente para conter o nome do dispositivo local. Caso contrário, o buffer precisa ser grande o suficiente para conter a cadeia de caracteres apontada por lpRemoteName ou o nome do recurso conectável cujo alias é apontado por lpRemoteName. Se esse erro for retornado, nenhuma conexão será feita. |
|
O sistema operacional não pode escolher automaticamente um redirecionamento local porque todos os dispositivos locais válidos estão em uso. |
|
A operação não pôde ser concluída, seja porque um componente de rede não foi iniciado ou porque o nome do recurso especificado não é reconhecido. |
|
A rede não está disponível. |
Comentários
Windows Server 2003 e 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 pela AuthenticationID. (Uma AuthenticationID é o 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 . GetLogicalDrives não retorna letras de unidade de rede criadas por uma 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.
Observação
O cabeçalho winnetwk.h define WNetUseConnection 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
| 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de