NetWkstaUserEnum, fonction (lmwksta.h)

Article
08/24/2023

La fonction NetWkstaUserEnum répertorie des informations sur tous les utilisateurs actuellement connectés à la station de travail. Cette liste inclut des ouvertures de session interactives, de service et par lots.

Syntaxe

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

Paramètres

[in] servername

Pointeur vers une chaîne qui spécifie le nom DNS ou NetBIOS du serveur distant sur lequel la fonction doit s’exécuter. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

[in] level

Spécifie le niveau d’informations des données. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
0	Retourne les noms des utilisateurs actuellement connectés à la station de travail. Le paramètre bufptr pointe vers un tableau de structures WKSTA_USER_INFO_0 .
1	Retourne les noms des utilisateurs actuels et des domaines auxquels la station de travail accède. Le paramètre bufptr pointe vers un tableau de structures WKSTA_USER_INFO_1 .

[out] bufptr

Pointeur vers la mémoire tampon qui reçoit les données. Le format de ces données dépend de la valeur du paramètre level . Cette mémoire tampon est allouée par le système et doit être libérée à l’aide de la fonction NetApiBufferFree . Notez que vous devez libérer la mémoire tampon même si la fonction échoue avec ERROR_MORE_DATA.

[in] prefmaxlen

Spécifie la longueur maximale par défaut des données retournées, en octets. Si vous spécifiez MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire requise pour les données. Si vous spécifiez une autre valeur dans ce paramètre, cela peut limiter le nombre d’octets retournés par la fonction. Si la taille de la mémoire tampon est insuffisante pour contenir toutes les entrées, la fonction retourne ERROR_MORE_DATA. Pour plus d’informations, consultez Mémoires tampons de fonction de gestion réseau et Longueurs de mémoire tampon des fonctions de gestion réseau.

[out] entriesread

Pointeur vers une valeur qui reçoit le nombre d’éléments réellement énumérés.

[out] totalentries

Pointeur vers une valeur qui reçoit le nombre total d’entrées qui auraient pu être énumérées à partir de la position de reprise actuelle. Notez que les applications doivent considérer cette valeur uniquement comme un indicateur.

[in, out] resumehandle

Pointeur vers une valeur qui contient un handle de cv utilisé pour poursuivre une recherche existante. Le handle doit être égal à zéro lors du premier appel et laisser inchangé pour les appels suivants. Si ce paramètre a la valeur NULL, aucun handle de reprise n’est stocké.

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_ACCESS_DENIED	L’utilisateur n’a pas accès aux informations demandées.
ERROR_MORE_DATA	D’autres entrées sont disponibles. Spécifiez une mémoire tampon suffisamment grande pour recevoir toutes les entrées.
ERROR_INVALID_LEVEL	Le paramètre level n’est pas valide.

Remarques

Notez que, étant donné que la fonction NetWkstaUserEnum répertorie les entrées pour les ouvertures de session de service et par lots, ainsi que pour les ouvertures de session interactives, la fonction peut retourner des entrées pour les utilisateurs qui se sont déconnectés d’une station de travail. Cela peut se produire, par exemple, lorsqu’un utilisateur appelle un service qui emprunte l’identité de l’utilisateur. Dans cette instance, NetWkstaUserEnum retourne une entrée pour l’utilisateur jusqu’à ce que le service cesse d’emprunter l’identité de l’utilisateur.

Windows Server 2003 et Windows XP : Si vous appelez cette fonction sur un contrôleur de domaine qui exécute Active Directory, l’accès est autorisé ou refusé en fonction de la liste de contrôle d’accès pour l’objet sécurisable. Pour activer l’accès anonyme, l’utilisateur Anonyme doit être membre du groupe « Accès compatible pré-Windows 2000 ». Cela est dû au fait que les jetons anonymes n’incluent pas le SID de groupe Tout le monde par défaut. Si vous appelez cette fonction sur un serveur ou une station de travail membre, tous les utilisateurs authentifiés peuvent afficher les informations. L’accès anonyme est également autorisé si le paramètre de stratégie RestrictAnonymous autorise l’accès anonyme. Si le paramètre de stratégie RestrictAnonymous n’autorise pas l’accès anonyme, seul un administrateur peut exécuter correctement la fonction. Les membres des groupes locaux Administrateurs et Serveur, Système et Opérateur d’impression peuvent également afficher des informations. Pour plus d’informations sur la restriction de l’accès anonyme, consultez Exigences de sécurité pour les fonctions de gestion réseau. Pour plus d’informations sur les ACL, les ACL et les jetons d’accès, consultez modèle Access Control.

Windows 2000 : Si vous appelez cette fonction sur un contrôleur de domaine qui exécute Active Directory, l’accès est autorisé ou refusé en fonction de la liste de contrôle d’accès (ACL) pour l’objet sécurisable. La liste de contrôle d’accès par défaut permet à tous les utilisateurs et membres authentifiés du groupe « Accès compatible pré-Windows 2000 » d’afficher les informations. Par défaut, le groupe « Accès compatible pré-Windows 2000 » inclut Tout le monde en tant que membre. Cela permet l’accès anonyme aux informations si le système autorise l’accès anonyme. Si vous appelez cette fonction sur un serveur ou une station de travail membre, tous les utilisateurs authentifiés peuvent afficher les informations. L’accès anonyme est également autorisé si le paramètre de stratégie RestrictAnonymous autorise l’accès anonyme.

Pour compiler une application qui utilise cette fonction, définissez la macro _WIN32_WINNT comme 0x0400 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Exemples

L’exemple de code suivant montre comment répertorier des informations sur tous les utilisateurs actuellement connectés à une station de travail à l’aide d’un appel à la fonction NetWkstaUserEnum . L’exemple appelle NetWkstaUserEnum, en spécifiant le niveau d’informations 0 ( WKSTA_USER_INFO_0). L’exemple effectue une boucle dans les entrées et imprime les noms des utilisateurs connectés à une station de travail. Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon d’informations et imprime le nombre total d’utilisateurs énumérés.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmwksta.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll