Função NetConnectionEnum (lmshare.h)

Artigo
08/24/2023

Lista todas as conexões feitas a um recurso compartilhado no servidor ou todas as conexões estabelecidas a partir de um computador específico. Se houver mais de um usuário usando essa conexão, será possível obter mais de uma estrutura para a mesma conexão, mas com um nome de usuário diferente.

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetConnectionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   qualifier,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resume_handle
);

Parâmetros

[in] servername

Ponteiro para uma cadeia de caracteres que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

Essa cadeia de caracteres será Unicode se _WIN32_WINNT ou FORCE_UNICODE estiver definido.

[in] qualifier

Ponteiro para uma cadeia de caracteres que especifica um nome de compartilhamento ou nome de computador para as conexões de interesse. Se for um nome de compartilhamento, todas as conexões feitas com esse nome de compartilhamento serão listadas. Se for um nome de computador (por exemplo, ele começa com dois caracteres de barra invertida), o NetConnectionEnum lista todas as conexões feitas desse computador para o servidor especificado.

Essa cadeia de caracteres será Unicode se _WIN32_WINNT ou FORCE_UNICODE estiver definido.

[in] level

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

Valor	Significado
0	Retornar identificadores de conexão. O parâmetro bufptr é um ponteiro para uma matriz de estruturas de CONNECTION_INFO_0 .
1	Retornar identificadores de conexão e informações de conexão. O parâmetro bufptr é um ponteiro para uma matriz de estruturas CONNECTION_INFO_1 .

[out] bufptr

Ponteiro para o endereço do buffer que recebe as informações. O formato desses dados depende do valor do parâmetro de nível .

Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree . Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA.

[in] prefmaxlen

Especifica o comprimento máximo preferencial dos dados retornados, em bytes. Se você especificar MAX_PREFERRED_LENGTH, a função alocará a quantidade de memória necessária para os dados. Se você especificar outro valor 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

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

[out] totalentries

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] resume_handle

Ponteiro para um valor que contém um identificador de currículo que é usado para continuar uma pesquisa de conexão existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se esse parâmetro for NULL, nenhum identificador de retomada 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.

Comentários

A associação de administrador, servidor ou operador de impressão ou grupo do Power User é necessária para executar com êxito a função NetConnectionEnum .

Exemplos

O exemplo de código a seguir demonstra como listar as conexões feitas a um recurso compartilhado com uma chamada para a função NetConnectionEnum . O exemplo chama NetConnectionEnum, especificando o nível de informações 1 (CONNECTION_INFO_1). Se houver entradas a serem retornadas, ela imprimirá os valores dos membros coni1_username e coni1_netname . Se não houver entradas a serem retornadas, o exemplo imprimirá uma mensagem apropriada. Por fim, o exemplo de código libera a memória alocada para o buffer de informações.

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <lm.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res, i, er = 0, tr = 0, resume = 0;
   PCONNECTION_INFO_1 p,b;
   LPTSTR lpszServer = NULL, lpszShare = NULL;

   if(argc<2)
      wprintf(L"Syntax: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
   else
   {
      //
      // The server is not the default local computer.
      //
      if(argc>2)
         lpszServer=argv[1];
      //
      // ShareName is always the last argument.
      //
      lpszShare=argv[argc - 1];
      //
      // Call the NetConnectionEnum function,
      //  specifying information level 1.
      //
      res=NetConnectionEnum(lpszServer, lpszShare, 1, (LPBYTE *) &p, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If no error occurred,
      //
      if(res == 0)
      {
         //
         // If there were any results,
         //
         if(er>0)
         {
            b=p;
            //
            // Loop through the entries; print user name and network name.
            //
            for(i=0;i<er;i++)
            {
               printf("%S\t%S\n", b->coni1_username,b->coni1_netname);
               b++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(p);
         }
         // Otherwise, print a message depending on whether 
         //  the qualifier parameter was a computer (\\ComputerName)
         //  or a share (ShareName).
         //
         else
         {
            if(lpszShare[0]=='\\')  
               printf("No connection to %S from %S\n", 
                  (lpszServer == NULL)?TEXT("LocalMachine"):lpszServer, lpszShare);
            else                       
               printf("No one connected to %S\\%S\n",
                  (lpszServer == NULL)?TEXT("\\\\LocalMachine"):lpszServer,lpszShare);
         }        
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %d\n",res);
   }
   return;
}

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmshare.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll