Funzione NetConnectionEnum (lmshare.h)

Elenca tutte le connessioni effettuate a una risorsa condivisa nel server o tutte le connessioni stabilite da un determinato computer. Se ci sono più utenti che usano questa connessione, è possibile ottenere più di una struttura per la stessa connessione, ma con un nome utente diverso.

Sintassi

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
);

Parametri

[in] servername

Puntatore a una stringa che specifica il nome DNS o NetBIOS del server remoto in cui eseguire la funzione. Se questo parametro è NULL, viene usato il computer locale.

Questa stringa è Unicode se è definita _WIN32_WINNT o FORCE_UNICODE .

[in] qualifier

Puntatore a una stringa che specifica un nome di condivisione o un nome computer per le connessioni di interesse. Se è un nome di condivisione, vengono elencate tutte le connessioni effettuate a tale nome di condivisione. Se si tratta di un nome computer (ad esempio, inizia con due caratteri barra rovesciata), NetConnectionEnum elenca tutte le connessioni effettuate dal computer al server specificato.

Questa stringa è Unicode se è definita _WIN32_WINNT o FORCE_UNICODE .

[in] level

Specifica il livello di informazioni dei dati. Questo parametro può avere uno dei valori seguenti.

[out] bufptr

Puntatore all'indirizzo del buffer che riceve le informazioni. Il formato di questi dati dipende dal valore del parametro di livello .

Questo buffer viene allocato dal sistema e deve essere liberato usando la funzione NetApiBufferFree . Si noti che è necessario liberare il buffer anche se la funzione ha esito negativo con ERROR_MORE_DATA.

[in] prefmaxlen

Specifica la lunghezza massima preferita dei dati restituiti, in byte. Se si specifica MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per i dati. Se si specifica un altro valore in questo parametro, può limitare il numero di byte restituiti dalla funzione. Se le dimensioni del buffer non sono sufficienti per contenere tutte le voci, la funzione restituisce ERROR_MORE_DATA. Per altre informazioni, vedere Buffer delle funzioni di gestione della rete e lunghezze del buffer delle funzioni di gestione della rete.

[out] entriesread

Puntatore a un valore che riceve il conteggio degli elementi effettivamente enumerati.

[out] totalentries

Puntatore a un valore che riceve il numero totale di voci che potrebbero essere state enumerate dalla posizione di ripresa corrente. Si noti che le applicazioni devono considerare questo valore solo come hint.

[in, out] resume_handle

Puntatore a un valore che contiene un handle di ripresa usato per continuare una ricerca di connessione esistente. L'handle deve essere zero nella prima chiamata e lasciato invariato per le chiamate successive. Se questo parametro è NULL, non viene archiviato alcun handle di ripresa.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NERR_Success.

Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema. Per un elenco di codici di errore, vedere Codici di errore di sistema.

Commenti

Per eseguire correttamente la funzione NetConnectionEnum , è necessario l'amministratore, il server o l'operatore di stampa o l'appartenenza al gruppo Power User.

Esempio

L'esempio di codice seguente illustra come elencare le connessioni effettuate a una risorsa condivisa con una chiamata alla funzione NetConnectionEnum . L'esempio chiama NetConnectionEnum, specificando il livello di informazioni 1 (CONNECTION_INFO_1). Se sono presenti voci da restituire, stampa i valori dei membri coni1_username e coni1_netname . Se non sono presenti voci da restituire, l'esempio stampa un messaggio appropriato. Infine, l'esempio di codice libera la memoria allocata per il buffer delle informazioni.

#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;
}

Requisiti

Vedi anche

CONNECTION_INFO_0

CONNECTION_INFO_1

Funzioni di gestione della rete

Panoramica sulla gestione della rete

Funzioni di condivisione di rete