Función NetWkstaUserEnum (lmwksta.h)

Artículo
08/24/2023

La función NetWkstaUserEnum muestra información sobre todos los usuarios que han iniciado sesión actualmente en la estación de trabajo. Esta lista incluye inicios de sesión interactivos, de servicio y por lotes.

Sintaxis

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

Parámetros

[in] servername

Puntero a una cadena que especifica el nombre DNS o NetBIOS del servidor remoto en el que se va a ejecutar la función. Si este parámetro es NULL, se usa el equipo local.

[in] level

Especifica el nivel de información de los datos. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
0	Devuelve los nombres de los usuarios que han iniciado sesión actualmente en la estación de trabajo. El parámetro bufptr apunta a una matriz de estructuras WKSTA_USER_INFO_0 .
1	Devuelve los nombres de los usuarios actuales y los dominios a los que accede la estación de trabajo. El parámetro bufptr apunta a una matriz de estructuras WKSTA_USER_INFO_1 .

[out] bufptr

Puntero al búfer que recibe los datos. El formato de estos datos depende del valor del parámetro level . El sistema asigna este búfer y se debe liberar mediante la función NetApiBufferFree . Tenga en cuenta que debe liberar el búfer incluso si se produce un error en la función con ERROR_MORE_DATA.

[in] prefmaxlen

Especifica la longitud máxima preferida de los datos devueltos, en bytes. Si especifica MAX_PREFERRED_LENGTH, la función asigna la cantidad de memoria necesaria para los datos. Si especifica otro valor en este parámetro, puede restringir el número de bytes que devuelve la función. Si el tamaño del búfer no es suficiente para contener todas las entradas, la función devuelve ERROR_MORE_DATA. Para obtener más información, consulte Network Management Function Buffers (Búferes de funciones de administración de red) y Network Management Function Buffer Lengths (Longitudes de búfer de funciones de administración de red).

[out] entriesread

Puntero a un valor que recibe el recuento de elementos enumerados realmente.

[out] totalentries

Puntero a un valor que recibe el número total de entradas que podrían haberse enumerado a partir de la posición de reanudación actual. Tenga en cuenta que las aplicaciones deben considerar este valor solo como sugerencia.

[in, out] resumehandle

Puntero a un valor que contiene un identificador de reanudación que se usa para continuar una búsqueda existente. El identificador debe ser cero en la primera llamada y dejar sin cambios para las llamadas posteriores. Si este parámetro es NULL, no se almacena ningún identificador de reanudación.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es NERR_Success.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El usuario no tiene acceso a la información pedida.
ERROR_MORE_DATA	Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas.
ERROR_INVALID_LEVEL	El parámetro level no es válido.

Comentarios

Tenga en cuenta que, dado que la función NetWkstaUserEnum enumera las entradas de inicios de sesión por lotes y de servicio, así como para inicios de sesión interactivos, la función puede devolver entradas para los usuarios que han cerrado la sesión en una estación de trabajo. Esto puede ocurrir, por ejemplo, cuando un usuario llama a un servicio que suplanta al usuario. En este caso, NetWkstaUserEnum devuelve una entrada para el usuario hasta que el servicio deja de suplantar al usuario.

Windows Server 2003 y Windows XP: Si llama a esta función en un controlador de dominio que ejecuta Active Directory, se permite o se deniega el acceso en función de la ACL para el objeto protegible. Para habilitar el acceso anónimo, el usuario Anónimo debe ser miembro del grupo "Acceso compatible con Pre-Windows 2000". Esto se debe a que los tokens anónimos no incluyen el SID del grupo Todos de forma predeterminada. Si llama a esta función en un servidor miembro o estación de trabajo, todos los usuarios autenticados pueden ver la información. También se permite el acceso anónimo si la configuración de directiva RestrictAnonymous permite el acceso anónimo. Si la configuración de directiva RestrictAnonymous no permite el acceso anónimo, solo un administrador puede ejecutar correctamente la función. Los miembros de los administradores y los grupos locales Servidor, Operador de sistema e impresión también pueden ver información. Para obtener más información sobre cómo restringir el acceso anónimo, vea Requisitos de seguridad para las funciones de administración de red. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Modelo.

Windows 2000: Si llama a esta función en un controlador de dominio que ejecuta Active Directory, se permite o se deniega el acceso en función de la lista de control de acceso (ACL) para el objeto protegible. La ACL predeterminada permite que todos los usuarios y miembros autenticados del grupo " Acceso compatible con Pre-Windows 2000" vean la información. De forma predeterminada, el grupo "Acceso compatible con Pre-Windows 2000" incluye Todos como miembro. Esto permite el acceso anónimo a la información si el sistema permite el acceso anónimo. Si llama a esta función en un servidor miembro o estación de trabajo, todos los usuarios autenticados pueden ver la información. También se permite el acceso anónimo si la configuración de directiva RestrictAnonymous permite el acceso anónimo.

Para compilar una aplicación que usa esta función, defina la macro _WIN32_WINNT como 0x0400 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Ejemplos

En el ejemplo de código siguiente se muestra cómo mostrar información sobre todos los usuarios que han iniciado sesión actualmente en una estación de trabajo mediante una llamada a la función NetWkstaUserEnum . El ejemplo llama a NetWkstaUserEnum, especificando el nivel de información 0 ( WKSTA_USER_INFO_0). El ejemplo recorre en bucle las entradas e imprime los nombres de los usuarios que han iniciado sesión en una estación de trabajo. Por último, el ejemplo de código libera la memoria asignada para el búfer de información e imprime el número total de usuarios enumerados.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	lmwksta.h (include Lm.h)
Library	Netapi32.lib
Archivo DLL	Netapi32.dll