Compartilhar via


Função NetWkstaUserEnum (lmwksta.h)

A função NetWkstaUserEnum lista informações sobre todos os usuários conectados atualmente à estação de trabalho. Esta lista inclui logons interativos, de serviço e de lote.

Sintaxe

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

Ponteiro para uma cadeia de caracteres que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

[in] level

Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
0
Retornar os nomes dos usuários conectados atualmente à estação de trabalho. O parâmetro bufptr aponta para uma matriz de estruturas WKSTA_USER_INFO_0 .
1
Retorne os nomes dos usuários atuais e os domínios acessados pela estação de trabalho. O parâmetro bufptr aponta para uma matriz de estruturas WKSTA_USER_INFO_1 .

[out] bufptr

Ponteiro para o buffer que recebe os dados. O formato desses dados depende do valor do parâmetro de nível . Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree . Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA.

[in] prefmaxlen

Especifica o comprimento máximo preferencial dos dados retornados, em bytes. Se você especificar MAX_PREFERRED_LENGTH, a função alocará a quantidade de memória necessária para os dados. Se você especificar outro valor nesse parâmetro, ele poderá restringir o número de bytes retornados pela função. Se o tamanho do buffer for insuficiente para manter todas as entradas, a função retornará ERROR_MORE_DATA. Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.

[out] entriesread

Ponteiro para um valor que recebe a contagem de elementos realmente enumerados.

[out] totalentries

Ponteiro para um valor que recebe o número total de entradas que poderiam ter sido enumeradas da posição de currículo atual. Observe que os aplicativos devem considerar esse valor apenas como uma dica.

[in, out] resumehandle

Ponteiro para um valor que contém um identificador de currículo que é usado para continuar uma pesquisa existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se esse parâmetro for NULL, nenhum identificador de retomada será armazenado.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro.

Código de retorno Descrição
ERROR_ACCESS_DENIED
O usuário não tem acesso às informações solicitadas.
ERROR_MORE_DATA
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas.
ERROR_INVALID_LEVEL
O parâmetro de nível é inválido.

Comentários

Observe que, como a função NetWkstaUserEnum lista entradas para logons de serviço e lote, bem como para logons interativos, a função pode retornar entradas para usuários que fizeram logoff de uma estação de trabalho. Isso pode ocorrer, por exemplo, quando um usuário chama um serviço que representa o usuário. Nesse caso, NetWkstaUserEnum retorna uma entrada para o usuário até que o serviço pare de representar o usuário.

Windows Server 2003 e Windows XP: Se você chamar essa função em um controlador de domínio que está executando o Active Directory, o acesso será permitido ou negado com base na ACL do objeto protegível. Para habilitar o acesso anônimo, o usuário Anônimo deve ser membro do grupo "Acesso compatível com o Pré-Windows 2000". Isso ocorre porque os tokens anônimos não incluem o SID do grupo Todos por padrão. Se você chamar essa função em um servidor membro ou estação de trabalho, todos os usuários autenticados poderão exibir as informações. O acesso anônimo também será permitido se a configuração de política RestrictAnonymous permitir acesso anônimo. Se a configuração de política RestrictAnonymous não permitir acesso anônimo, somente um administrador poderá executar a função com êxito. Os membros dos administradores e os grupos locais Servidor, Sistema e Operador de Impressão também podem exibir informações. Para obter mais informações sobre como restringir o acesso anônimo, consulte Requisitos de segurança para as funções de gerenciamento de rede. Para obter mais informações sobre ACLs, ACEs e tokens de acesso, consulte Controle de Acesso Model.

Windows 2000: Se você chamar essa função em um controlador de domínio que está executando o Active Directory, o acesso será permitido ou negado com base na ACL (lista de controle de acesso) do objeto protegível. A ACL padrão permite que todos os usuários autenticados e membros do grupo " Acesso compatível com o Windows 2000" exibam as informações. Por padrão, o grupo "Acesso compatível com Pré-Windows 2000" inclui Todos como membro. Isso habilita o acesso anônimo às informações se o sistema permitir acesso anônimo. Se você chamar essa função em um servidor membro ou estação de trabalho, todos os usuários autenticados poderão exibir as informações. O acesso anônimo também será permitido se a configuração de política RestrictAnonymous permitir acesso anônimo.

Para compilar um aplicativo que usa essa função, defina a macro _WIN32_WINNT como 0x0400 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Exemplos

O exemplo de código a seguir demonstra como listar informações sobre todos os usuários conectados atualmente a uma estação de trabalho usando uma chamada para a função NetWkstaUserEnum . O exemplo chama NetWkstaUserEnum, especificando o nível de informações 0 ( WKSTA_USER_INFO_0). O exemplo percorre as entradas e imprime os nomes dos usuários conectados a uma estação de trabalho. Por fim, o exemplo de código libera a memória alocada para o buffer de informações e imprime o número total de usuários 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 Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho lmwksta.h (inclua Lm.h)
Biblioteca Netapi32.lib
DLL Netapi32.dll

Confira também

NetWkstaGetInfo

NetWkstaSetInfo

Funções de gerenciamento de rede

Visão geral do gerenciamento de rede

WKSTA_USER_INFO_0

WKSTA_USER_INFO_1

Funções de usuário de estação de trabalho e estação de trabalho