Функция NetQueryDisplayInformation (lmaccess.h)

Статья
08/24/2023

Функция NetQueryDisplayInformation возвращает сведения об учетной записи пользователя, компьютере или группе. Вызовите эту функцию, чтобы быстро перечислить сведения об учетной записи для отображения в пользовательских интерфейсах.

Синтаксис

NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
  [in]  LPCWSTR ServerName,
  [in]  DWORD   Level,
  [in]  DWORD   Index,
  [in]  DWORD   EntriesRequested,
  [in]  DWORD   PreferredMaximumLength,
  [out] LPDWORD ReturnedEntryCount,
  [out] PVOID   *SortedBuffer
);

Параметры

[in] ServerName

Указатель на константную строку, указывающую DNS- или NetBIOS-имя удаленного сервера, на котором выполняется функция. Если этот параметр имеет значение NULL, используется локальный компьютер.

[in] Level

Указывает уровень информации о данных. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
1	Возврат сведений об учетной записи пользователя. Параметр SortedBuffer указывает на массив NET_DISPLAY_USER структур.
2	Возврат сведений об отдельных компьютерах. Параметр SortedBuffer указывает на массив NET_DISPLAY_MACHINE структур.
3	Возвращает сведения об учетной записи группы. Параметр SortedBuffer указывает на массив NET_DISPLAY_GROUP структур.

[in] Index

Указывает индекс первой записи, для которой требуется получить сведения. Укажите ноль, чтобы получить сведения об учетной записи, начиная с первой отображаемой информации. Дополнительные сведения см. в разделе "Примечания".

[in] EntriesRequested

Указывает максимальное количество записей, для которых требуется получить сведения. В Windows 2000 и более поздних версиях каждый вызов NetQueryDisplayInformation возвращает не более 100 объектов.

[in] PreferredMaximumLength

Указывает предпочтительный максимальный размер буфера, выделенного системой, в байтах, возвращаемого в параметре SortedBuffer . Рекомендуется задать для этого параметра значение MAX_PREFERRED_LENGTH.

[out] ReturnedEntryCount

Указатель на значение, которое получает количество записей в буфере, возвращаемых в параметре SortedBuffer . Если этот параметр равен нулю, отсутствуют записи с указанным индексом. Записи могут возвращаться, если возвращаемое значение функции равно NERR_Success или ERROR_MORE_DATA.

[out] SortedBuffer

Указатель на буфер, получающий указатель на буфер, выделенный системой, который указывает отсортированный список запрошенных сведений. Формат этих данных зависит от значения параметра Level . Так как этот буфер выделяется системой, его необходимо освободить с помощью функции NetApiBufferFree . Обратите внимание, что буфер необходимо освободить, даже если функция завершается сбоем с ERROR_MORE_DATA. Дополнительные сведения см. в следующем разделе Возвращаемые значения и в разделах Network Management Function Buffers (Буферы функций управления сетью ) и Network Management Function Buffers (Длина буфера функции управления сетью).

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет NERR_Success.

Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.

Код возврата	Описание
ERROR_ACCESS_DENIED	У пользователя нет доступа к запрошенной информации.
ERROR_INVALID_LEVEL	Параметр Level указывает недопустимое значение.
ERROR_MORE_DATA	Доступны дополнительные записи. То есть последняя запись, возвращенная в параметре SortedBuffer , не является последней доступной записью. Чтобы получить дополнительные записи, снова вызовите NetQueryDisplayInformation с параметром Index , для которого задано значение, возвращенное в элементе next_index последней записи в SortedBuffer. Обратите внимание, что значение элемента next_index не следует использовать только для получения дополнительных данных с помощью дополнительных вызовов NetQueryDisplayInformation.

Если вы вызываете эту функцию на контроллере домена под управлением Active Directory, доступ разрешен или запрещен на основе списка управления доступом (ACL) для защищаемого объекта. Список управления доступом по умолчанию позволяет просматривать сведения всем пользователям, прошедшим проверку подлинности, и членам группы "Доступ, совместимый с Windows 2000". Если вы вызываете эту функцию на рядовом сервере или рабочей станции, все пользователи, прошедшие проверку подлинности, смогут просматривать сведения. Сведения об анонимном доступе и ограничении анонимного доступа на этих платформах см. в разделе Требования к безопасности для функций управления сетью. Дополнительные сведения о списках управления доступом, ACE и маркерах доступа см. в разделе модель контроль доступа.

Функция NetQueryDisplayInformation возвращает только сведения, к которым вызывающий объект имеет доступ на чтение. Вызывающий объект должен иметь доступ List Contents к объекту Domain и Перечислить полный доступ к домену SAM для объекта SAM Server, расположенного в контейнере System.

Функции NetQueryDisplayInformation и NetGetDisplayInformationIndex предоставляют эффективный механизм перечисления учетных записей пользователей и групп. По возможности используйте эти функции вместо функции NetUserEnum или NetGroupEnum .

Чтобы перечислить доверяющие домены или учетные записи компьютеров-членов, вызовите NetUserEnum, указав соответствующее значение фильтра для получения необходимых сведений об учетной записи. Чтобы перечислить доверенные домены, вызовите функцию LsaEnumerateTrustedDomains или LsaEnumerateTrustedDomainsEx .

Количество записей, возвращаемых этой функцией, зависит от дескриптора безопасности, расположенного в корневом объекте домена. API возвращает первые 100 записей или весь набор записей в домене в зависимости от привилегий доступа пользователя. ACE, используемый для управления этим поведением, является SAM-Enumerate-Entire-Domain и по умолчанию предоставляется пользователям, прошедшим проверку подлинности. Администраторы могут изменить этот параметр, чтобы разрешить пользователям перечислять весь домен.

Каждый вызов NetQueryDisplayInformation возвращает не более 100 объектов. Вызов функции NetQueryDisplayInformation для перечисления сведений об учетной записи домена может быть дорогостоящим с точки зрения производительности. Если вы программируете для Active Directory, возможно, вы сможете использовать методы в интерфейсе IDirectorySearch для создания страничных запросов к домену. Дополнительные сведения см. в разделах IDirectorySearch::SetSearchPreference и IDirectorySearch::ExecuteSearch. Чтобы перечислить доверенные домены, вызовите функцию LsaEnumerateTrustedDomainsEx .

Примеры

В следующем примере кода показано, как вернуть сведения об учетной записи группы с помощью вызова функции NetQueryDisplayInformation . Если пользователь указывает имя сервера, пример сначала вызывает функцию MultiByteToWideChar для преобразования имени в Юникод. Пример вызывает NetQueryDisplayInformation, указывая уровень информации 3 (NET_DISPLAY_GROUP) для получения сведений об учетной записи группы. Если есть записи для возврата, образец возвращает данные и выводит сведения о группе. Наконец, пример кода освобождает память, выделенную для информационного буфера.

#ifndef UNICODE
#define UNICODE
#endif

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

#pragma comment(lib, "netapi32.lib")

void main( int argc, char *argv[ ] )
{
   PNET_DISPLAY_GROUP pBuff, p;
   DWORD res, dwRec, i = 0;
   //
   // You can pass a NULL or empty string
   //  to retrieve the local information.
   //
   TCHAR szServer[255]=TEXT(""); 

   if(argc > 1) 
      //
      // Check to see if a server name was passed;
      //  if so, convert it to Unicode.
      //
      MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255); 

   do // begin do
   { 
      //
      // Call the NetQueryDisplayInformation function;
      //   specify information level 3 (group account information).
      //
      res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
      //
      // If the call succeeds,
      //
      if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
      {
         p = pBuff;
         for(;dwRec>0;dwRec--)
         {
            //
            // Print the retrieved group information.
            //
            printf("Name:      %S\n"
                  "Comment:   %S\n"
                  "Group ID:  %u\n"
                  "Attributes: %u\n"
                  "--------------------------------\n",
                  p->grpi3_name,
                  p->grpi3_comment,
                  p->grpi3_group_id,
                  p->grpi3_attributes);
            //
            // If there is more data, set the index.
            //
            i = p->grpi3_next_index;
            p++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pBuff);
      }
      else
         printf("Error: %u\n", res);
   //
   // Continue while there is more data.
   //
   } while (res==ERROR_MORE_DATA); // end do
   return;
}

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	lmaccess.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll