Função NetUseEnum (lmuse.h)

Artigo
08/24/2023

A função NetUseEnum lista todas as conexões atuais entre o computador local e os recursos em servidores remotos.

Você também pode usar as funções WNetOpenEnum e WNetEnumResource para enumerar recursos ou conexões de rede.

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetUseEnum(
  [in]      LMSTR   UncServerName,
  [in]      DWORD   LevelFlags,
  [out]     LPBYTE  *BufPtr,
  [in]      DWORD   PreferedMaximumSize,
  [out]     LPDWORD EntriesRead,
  [out]     LPDWORD TotalEntries,
  [in, out] LPDWORD ResumeHandle
);

Parâmetros

[in] UncServerName

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 de Protocolo de Acesso Remoto herdado.

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

[in] LevelFlags

O nível de informações dos dados solicitados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
0	Especifica um nome de dispositivo local e o nome do compartilhamento de um recurso remoto. O parâmetro BufPtr aponta para uma matriz de estruturas de USE_INFO_0 .
1	Especifica informações sobre a conexão entre um dispositivo local e um recurso compartilhado, incluindo status de conexão e tipo. O parâmetro BufPtr aponta para uma matriz de estruturas de 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 de conexão, o tipo de conexão, o nome de usuário e o nome de domínio. O parâmetro BufPtr aponta para uma matriz de estruturas USE_INFO_2 .

[out] BufPtr

Um ponteiro para o buffer que recebe as estruturas de informações. O formato desses dados depende do valor do parâmetro Level . Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree quando as informações não forem mais necessárias. Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA.

[in] PreferedMaximumSize

O comprimento máximo preferencial, em bytes, dos dados a serem retornados. Se MAX_PREFERRED_LENGTH for especificado, a função alocará a quantidade de memória necessária para os dados. Se outro valor for especificado nesse parâmetro, ele poderá restringir o número de bytes retornados pela função. Se o tamanho do buffer for insuficiente para manter todas as entradas, a função retornará ERROR_MORE_DATA. Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.

[out] EntriesRead

Um ponteiro para um valor que recebe a contagem de elementos realmente enumerados.

[out] TotalEntries

Um ponteiro para um valor que recebe o número total de entradas que poderiam ter sido enumeradas da posição de currículo atual. Observe que os aplicativos devem considerar esse valor apenas como uma dica.

[in, out] ResumeHandle

Um ponteiro para um valor que contém um identificador de currículo que é usado para continuar a pesquisa. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se ResumeHandle for NULL, nenhum identificador de currículo será armazenado.

Valor retornado

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.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado nos parâmetros BufPtr ou entriesread .
ERROR_MORE_DATA	Há mais dados a serem retornados. Esse erro será retornado se o tamanho do buffer for insuficiente para manter todas as entradas.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se o parâmetro UncServerName não for NULL e o servidor remoto não oferecer suporte a chamadas RPC remotas usando o mecanismo herdado do Protocolo de Acesso Remoto.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

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

Para recuperar informações sobre uma conexão de rede, você pode chamar a função NetUseGetInfo .

Essa função se aplica somente ao cliente do Bloco de Mensagens do Servidor (Estação de Trabalho do Gerenciador de LAN). A função NetUseEnum não dá suporte a compartilhamentos dfs (sistema de arquivos distribuídos). Para enumerar compartilhamentos usando um provedor de rede diferente (WebDAV ou um compartilhamento DFS, por exemplo), use as funções WNetOpenEnum, WNetEnumResource e WNetCloseEnum .

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