Funzione NetSessionEnum (lmshare.h)

Fornisce informazioni sulle sessioni stabilite in un server.

Sintassi

NET_API_STATUS NET_API_FUNCTION NetSessionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   UncClientName,
  [in]      LMSTR   username,
  [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.

[in] UncClientName

Puntatore a una stringa che specifica il nome della sessione del computer per cui le informazioni devono essere restituite. Se questo parametro è NULL, NetSessionEnum restituisce informazioni per tutte le sessioni computer nel server.

[in] username

Puntatore a una stringa che specifica il nome dell'utente per cui le informazioni devono essere restituite. Se questo parametro è NULL, NetSessionEnum restituisce informazioni per tutti gli utenti.

[in] level

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

[out] bufptr

Puntatore al buffer che riceve i dati. 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 contenente un handle di ripresa usato per continuare una ricerca di sessione esistente. L'handle deve essere zero nella prima chiamata e lasciato invariato per le chiamate successive. Se resume_handle è 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 può essere uno dei codici di errore seguenti.

Commenti

Solo i membri del gruppo locale Administrators o Server Operator possono eseguire correttamente la funzione NetSessionEnum a livello 1 o livello 2.

Se si sta programmando per Active Directory, potrebbe essere possibile chiamare determinati metodi di Active Directory Service Interface (ADSI) per ottenere la stessa funzionalità che è possibile ottenere chiamando le funzioni sessione di gestione della rete. Per altre informazioni, vedere IADsSession e IADsFileServiceOperations.

Esempio

L'esempio di codice seguente illustra come recuperare informazioni sulle sessioni correnti usando una chiamata alla funzione NetSessionEnum . L'esempio chiama NetSessionEnum, specificando il livello di informazioni 10 ( SESSION_INFO_10). L'esempio scorre le voci e stampa le informazioni recuperate. Infine, il codice stampa il numero totale di sessioni enumerate e libera la memoria allocata per il buffer informativo.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "Netapi32.lib")

#include <stdio.h>
#include <assert.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPSESSION_INFO_10 pBuf = NULL;
   LPSESSION_INFO_10 pTmpBuf;
   DWORD dwLevel = 10;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   LPTSTR pszServerName = NULL;
   LPTSTR pszClientName = NULL;
   LPTSTR pszUserName = NULL;
   NET_API_STATUS nStatus;
   //
   // Check command line arguments.
   //
   if (argc > 4)
   {
      wprintf(L"Usage: %s [\\\\ServerName] [\\\\ClientName] [UserName]\n", argv[0]);
      exit(1);
   }

   if (argc >= 2)
      pszServerName = argv[1];

   if (argc >= 3)
      pszClientName = argv[2];

   if (argc == 4)
      pszUserName = argv[3];
   //
   // Call the NetSessionEnum function, specifying level 10.
   //
   do // begin do
   {
      nStatus = NetSessionEnum(pszServerName,
                               pszClientName,
                               pszUserName,
                               dwLevel,
                               (LPBYTE*)&pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries.
            //
            for (i = 0; (i < dwEntriesRead); i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the retrieved data. 
               //
               wprintf(L"\n\tClient: %s\n", pTmpBuf->sesi10_cname);
               wprintf(L"\tUser:   %s\n", pTmpBuf->sesi10_username);
               printf("\tActive: %d\n", pTmpBuf->sesi10_time);
               printf("\tIdle:   %d\n", pTmpBuf->sesi10_idle_time);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, indicate a system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      //
      // Free the allocated memory.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   }
   // 
   // Continue to call NetSessionEnum while 
   //  there are more entries. 
   // 
   while (nStatus == ERROR_MORE_DATA); // end do

   // Check again for an allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of sessions enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Requisiti

Vedi anche

NetSessionGetInfo

Funzioni di gestione della rete

Panoramica sulla gestione della rete

SESSION_INFO_0

SESSION_INFO_1

SESSION_INFO_10

SESSION_INFO_2

SESSION_INFO_502

Funzioni di sessione