Função WNetUseConnectionA (winnetwk.h)

Artigo
11/20/2024

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 principal diferença é que WNetUseConnection pode selecionar automaticamente um dispositivo local não utilizado para redirecionar para o recurso de rede.

Sintaxe

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          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 seguintes membros da estrutura de NETRESOURCE.

Membro	Significado
dwType	Especifica o tipo de recurso ao qual se conectar. É mais eficiente especificar um tipo de recurso nesse membro, como RESOURCETYPE_DISK ou RESOURCETYPE_PRINT. No entanto, se o membro lpLocalName for NULL ou se ele apontar para uma cadeia de caracteres vazia e CONNECT_REDIRECT não estiver definido, dwType poderá ser RESOURCETYPE_ANY. Esse método só funcionará se a função não escolher automaticamente um dispositivo para redirecionar para o recurso de rede. Embora esse membro seja necessário, suas informações podem ser ignoradas pelo provedor de serviços de rede.
lpLocalName	Ponteiro para um cadeia de caracteresterminada nula 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 estiver NULL, ocorrerá uma conexão com a rede sem redirecionamento. Se o valor CONNECT_REDIRECT for definido no parâmetro dwFlags ou se a rede exigir um dispositivo local redirecionado, a função escolherá um dispositivo local para redirecionar e retornará o nome do dispositivo no parâmetro lpAccessName.
lpRemoteName	Ponteiro para um cadeia de caracteresterminada nula 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	Ponteiro para um cadeia de caracteresterminada nula 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 estiver NULL, o sistema operacional tentará fazer uma conexão apenas com o provedor de rede nomeado. Você deve definir esse membro somente se souber o provedor de rede que deseja usar. Caso contrário, permita que o sistema operacional determine para qual provedor o nome da rede é mapeado.

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 constante cadeia de caracteresterminada nula 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 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 constante cadeia de caracteres nulaterminada 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 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
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 lpLocalName membro do 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 de rede globais (como unidades de disco). Observe que as versões anteriores atribuídas à unidade começam com C: e terminam com Z:.
CONNECT_UPDATE_PROFILE	Esse sinalizador instrui o sistema operacional a armazenar a conexão de recurso de rede. Se esse sinalizador de bits 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 que não têm êxito ou conexões sem dispositivo. (Uma conexão sem dispositivo ocorre quando lpLocalName é NULL ou quando aponta para uma cadeia de caracteres vazia.) Se esse sinalizador de bits 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 oferecer suporte ao salvamento de credenciais, esse sinalizador será ignorado. Esse sinalizador também é ignorado, a menos que você defina o sinalizador de 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. Esse parâmetro pode ser NULL.

Se esse parâmetro for especificado e o lpLocalName membro 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 retorna o tamanho do buffer necessário neste 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	Significado
CONNECT_LOCALDRIVE	Se esse sinalizador for definido, a conexão foi feita usando um redirecionamento de dispositivo local. Se o parâmetro lpAccessName apontar para um buffer, o nome do dispositivo local será copiado para o buffer.

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 local especificado pelo membro lpLocalName já está conectado a um recurso de rede.
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 porque o nome do recurso é inválido ou porque o recurso nomeado não pode ser localizado.
ERROR_BAD_PROVIDER	O valor especificado pelo membro lpProvider não corresponde a nenhum provedor.
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_EXTENDED_ERROR	Ocorreu um erro específico da rede. Para obter uma descrição do erro, chame a função WNetGetLastError.
ERROR_INVALID_ADDRESS	O chamador passou um ponteiro para um buffer que não pôde ser acessado.
ERROR_INVALID_PARAMETER	Esse erro é resultado de uma das seguintes condições: O membro lpRemoteName é NULL. Além disso, lpAccessName não é NULL, mas lpBufferSize é NULL ou aponta para zero. O membro dwType não é RESOURCETYPE_DISK nem RESOURCETYPE_PRINT. Além disso, CONNECT_REDIRECT é definido em dwFlags e lpLocalName é NULL ou a conexão é para uma rede que requer o redirecionamento de um dispositivo local.
ERROR_INVALID_PASSWORD	A senha especificada é inválida e o sinalizador de CONNECT_INTERACTIVE não está definido.
ERROR_MORE_DATA	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 lpRemoteNameou o nome do recurso conectável cujo alias é apontado por lpRemoteName. Se esse erro for retornado, nenhuma conexão foi feita.
ERROR_NO_MORE_ITEMS	O sistema operacional não pode escolher automaticamente um redirecionamento local porque todos os dispositivos locais válidos estão em uso.
ERROR_NO_NET_OR_BAD_PATH	Não foi possível concluir a operação porque um componente de rede não foi iniciado ou porque o nome do recurso especificado não foi reconhecido.
ERROR_NO_NETWORK	A rede não está disponível.

Observações

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 MS-DOS dispositivos 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 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.

Nota

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

WNetGetConnection

Visão geral WNet (Rede windows)

funções de rede do Windows

WnetCancelConnection

Compartilhar via