Funzione NetWkstaUserEnum (lmwksta.h)

La funzione NetWkstaUserEnum elenca informazioni su tutti gli utenti attualmente connessi alla workstation. Questo elenco include accessi interattivi, di servizio e batch.

Sintassi

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

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

Puntatore a un valore contenente un handle di ripresa utilizzato per continuare una ricerca 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 può essere uno dei codici di errore seguenti.

Commenti

Si noti che poiché la funzione NetWkstaUserEnum elenca le voci per i log di servizio e batch, nonché per gli accessi interattivi, la funzione può restituire voci per gli utenti che hanno eseguito la disconnessione da una workstation. Ciò può verificarsi, ad esempio, quando un utente chiama un servizio che rappresenta l'utente. In questa istanza NetWkstaUserEnum restituisce una voce per l'utente finché il servizio non smette di rappresentare l'utente.

Windows Server 2003 e Windows XP: Se si chiama questa funzione in un controller di dominio che esegue Active Directory, l'accesso è consentito o negato in base all'elenco di controllo di accesso per l'oggetto a protezione diretta. Per abilitare l'accesso anonimo, l'utente Anonimo deve essere membro del gruppo di accesso compatibile con "Pre-Windows 2000". Questo perché i token anonimi non includono il SID del gruppo Tutti per impostazione predefinita. Se si chiama questa funzione in un server membro o in una workstation, tutti gli utenti autenticati possono visualizzare le informazioni. L'accesso anonimo è consentito anche se l'impostazione dei criteri RestrictAnonymous consente l'accesso anonimo. Se l'impostazione dei criteri RestrictAnonymous non consente l'accesso anonimo, solo un amministratore può eseguire correttamente la funzione. I membri degli amministratori e i gruppi locali server, sistema e operatore di stampa possono visualizzare anche le informazioni. Per altre informazioni sulla limitazione dell'accesso anonimo, vedere Requisiti di sicurezza per le funzioni di gestione della rete. Per altre informazioni sugli elenchi di controllo di accesso, sugli ACL e sui token di accesso, vedere Controllo di accesso Modello.

Windows 2000: Se si chiama questa funzione in un controller di dominio che esegue Active Directory, l'accesso è consentito o negato in base all'elenco di controllo di accesso (ACL) per l'oggetto a protezione diretta. L'elenco di controllo di accesso predefinito consente a tutti gli utenti autenticati e ai membri del gruppo " Accesso compatibile con Windows 2000" di pre-Windows 2000 per visualizzare le informazioni. Per impostazione predefinita, il gruppo "Accesso compatibile con Windows 2000" include Tutti come membro. Ciò consente l'accesso anonimo alle informazioni se il sistema consente l'accesso anonimo. Se si chiama questa funzione in un server membro o in una workstation, tutti gli utenti autenticati possono visualizzare le informazioni. L'accesso anonimo è consentito anche se l'impostazione dei criteri RestrictAnonymous consente l'accesso anonimo.

Per compilare un'applicazione che usa questa funzione, definire la macro _WIN32_WINNT come 0x0400 o successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Esempio

L'esempio di codice seguente illustra come elencare informazioni su tutti gli utenti attualmente connessi a una workstation usando una chiamata alla funzione NetWkstaUserEnum . L'esempio chiama NetWkstaUserEnum, specificando il livello di informazioni 0 ( WKSTA_USER_INFO_0). L'esempio scorre le voci e stampa i nomi degli utenti connessi a una workstation. Infine, l'esempio di codice libera la memoria allocata per il buffer delle informazioni e stampa il numero totale di utenti enumerati.

#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[])
{
   LPWKSTA_USER_INFO_0 pBuf = NULL;
   LPWKSTA_USER_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPWSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   fwprintf(stderr, L"\nUsers currently logged on %s:\n", pszServerName);
   //
   // Call the NetWkstaUserEnum function, specifying level 0.
   //
   do // begin do
   {
      nStatus = NetWkstaUserEnum( pszServerName,
                                  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)
               {
                  //
                  // Only members of the Administrators local group
                  //  can successfully execute NetWkstaUserEnum
                  //  locally and on a remote server.
                  //
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the user logged on to the workstation. 
               //
               wprintf(L"\t-- %s\n", pTmpBuf->wkui0_username);

               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 NetWkstaUserEnum while 
   //  there are more entries. 
   // 
   while (nStatus == ERROR_MORE_DATA); // end do
   //
   // Check again for allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of workstation users.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Requisiti

Vedi anche

NetWkstaGetInfo

NetWkstaSetInfo

Funzioni di gestione della rete

Panoramica sulla gestione della rete

WKSTA_USER_INFO_0

WKSTA_USER_INFO_1

Funzioni utente workstation e workstation