Função WNetGetConnectionA (winnetwk.h)

Artigo
11/20/2024

A função WNetGetConnection recupera o nome do recurso de rede associado a um dispositivo local.

Sintaxe

DWORD WNetGetConnectionA(
  [in]      LPCSTR  lpLocalName,
  [out]     LPSTR   lpRemoteName,
  [in, out] LPDWORD lpnLength
);

Parâmetros

[in] lpLocalName

Ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome do dispositivo local para o qual obter o nome da rede.

[out] lpRemoteName

Ponteiro para uma cadeia de caracteres terminada em nulo que recebe o nome remoto usado para fazer a conexão.

[in, out] lpnLength

Ponteiro para uma variável que especifica o tamanho do buffer apontado pelo parâmetro lpRemoteName, em caracteres. Se a função falhar porque o buffer não é grande o suficiente, esse parâmetro retorna o tamanho do buffer necessário.

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_BAD_DEVICE	A cadeia de caracteres apontada pelo parâmetro lpLocalName é inválida.
ERROR_NOT_CONNECTED	O dispositivo especificado por lpLocalName não é um dispositivo redirecionado. Para obter mais informações, consulte a seção Comentários a seguir.
ERROR_MORE_DATA	O buffer é muito pequeno. O parâmetro lpnLength aponta para uma variável que contém o tamanho do buffer necessário. Mais entradas estão disponíveis com chamadas subsequentes.
ERROR_CONNECTION_UNAVAIL	O dispositivo não está conectado no momento, mas é uma conexão persistente. Para obter mais informações, consulte a seção Comentários a seguir.
ERROR_NO_NETWORK	A rede não está disponível.
ERROR_EXTENDED_ERROR	Ocorreu um erro específico da rede. Para obter uma descrição do erro, chame a função WNetGetLastError.
ERROR_NO_NET_OR_BAD_PATH	Nenhum dos provedores reconhece o nome local como tendo uma conexão. No entanto, a rede não está disponível para pelo menos um provedor ao qual a conexão pode pertencer.

Observações

Se a conexão de rede tiver sido feita usando a rede do Microsoft LAN Manager e o aplicativo de chamada estiver em execução em uma sessão de logon diferente do aplicativo que fez a conexão, uma chamada para a função WNetGetConnection para o dispositivo local associado falhará. A função falha com ERROR_NOT_CONNECTED ou ERROR_CONNECTION_UNAVAIL. Isso ocorre porque uma conexão feita usando o Microsoft LAN Manager fica visível apenas para aplicativos em execução na mesma sessão de logon que o aplicativo que fez a conexão. (Para impedir que a chamada para WNetGetConnection falhe, não é suficiente que o aplicativo esteja em execução na conta de usuário que criou a conexão.)

Windows Server 2003 e Windows XP: Essa função consulta os namespaces do dispositivo MS-DOS associados 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.

Exemplos

Para obter um exemplo de código que ilustra como usar a função WNetGetConnection para recuperar o nome do recurso de rede associado a um dispositivo local, consulte Recuperando o nome da conexão.

Nota

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

WNetGetUser

Visão geral WNet (Rede windows)

funções de rede do Windows

Compartilhar via