Export (0) Print
Expand All
Expand Minimize

NetQueryDisplayInformation function

The NetQueryDisplayInformation function returns user account, computer, or group account information. Call this function to quickly enumerate account information for display in user interfaces.

Syntax


NET_API_STATUS NetQueryDisplayInformation(
  _In_   LPCWSTR ServerName,
  _In_   DWORD Level,
  _In_   DWORD Index,
  _In_   DWORD EntriesRequested,
  _In_   DWORD PreferredMaximumLength,
  _Out_  LPDWORD ReturnedEntryCount,
  _Out_  PVOID *SortedBuffer
);

Parameters

ServerName [in]

Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used.

Level [in]

Specifies the information level of the data. This parameter can be one of the following values.

ValueMeaning
1

Return user account information. The SortedBuffer parameter points to an array of NET_DISPLAY_USER structures.

2

Return individual computer information. The SortedBuffer parameter points to an array of NET_DISPLAY_MACHINE structures.

3

Return group account information. The SortedBuffer parameter points to an array of NET_DISPLAY_GROUP structures.

 

Index [in]

Specifies the index of the first entry for which to retrieve information. Specify zero to retrieve account information beginning with the first display information entry. For more information, see the following Remarks section.

EntriesRequested [in]

Specifies the maximum number of entries for which to retrieve information. On Windows 2000 and later, each call to NetQueryDisplayInformation returns a maximum of 100 objects.

PreferredMaximumLength [in]

Specifies the preferred maximum size, in bytes, of the system-allocated buffer returned in the SortedBuffer parameter. It is recommended that you set this parameter to MAX_PREFERRED_LENGTH.

ReturnedEntryCount [out]

Pointer to a value that receives the number of entries in the buffer returned in the SortedBuffer parameter. If this parameter is zero, there are no entries with an index as large as that specified. Entries may be returned when the function's return value is either NERR_Success or ERROR_MORE_DATA.

SortedBuffer [out]

Pointer to a buffer that receives a pointer to a system-allocated buffer that specifies a sorted list of the requested information. The format of this data depends on the value of the Level parameter. Because this buffer is allocated by the system, it must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA. For more information, see the following Return Values section, and the topics Network Management Function Buffers and Network Management Function Buffer Lengths.

Return value

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Return codeDescription
ERROR_ACCESS_DENIED

The user does not have access to the requested information.

ERROR_INVALID_LEVEL

The Level parameter specifies an invalid value.

ERROR_MORE_DATA

More entries are available. That is, the last entry returned in the SortedBuffer parameter is not the last entry available. To retrieve additional entries, call NetQueryDisplayInformation again with the Index parameter set to the value returned in the next_index member of the last entry in SortedBuffer. Note that you should not use the value of the next_index member for any purpose except to retrieve more data with additional calls to NetQueryDisplayInformation.

 

Remarks

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the access control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. If you call this function on a member server or workstation, all authenticated users can view the information. For information about anonymous access and restricting anonymous access on these platforms, see Security Requirements for the Network Management Functions. For more information on ACLs, ACEs, and access tokens, see Access Control Model.

The NetQueryDisplayInformation function only returns information to which the caller has Read access. The caller must have List Contents access to the Domain object, and Enumerate Entire SAM Domain access on the SAM Server object located in the System container.

The NetQueryDisplayInformation and NetGetDisplayInformationIndex functions provide an efficient mechanism for enumerating user and group accounts. When possible, use these functions instead of the NetUserEnum function or the NetGroupEnum function.

To enumerate trusting domains or member computer accounts, call NetUserEnum, specifying the appropriate filter value to obtain the account information you require. To enumerate trusted domains, call the LsaEnumerateTrustedDomains or LsaEnumerateTrustedDomainsEx function.

The number of entries returned by this function depends on the security descriptor located on the root domain object. The API will return either the first 100 entries or the entire set of entries in the domain, depending on the access privileges of the user. The ACE used to control this behavior is "SAM-Enumerate-Entire-Domain", and is granted to Authenticated Users by default. Administrators can modify this setting to allow users to enumerate the entire domain.

Each call to NetQueryDisplayInformation returns a maximum of 100 objects. Calling the NetQueryDisplayInformation function to enumerate domain account information can be costly in terms of performance. If you are programming for Active Directory, you may be able to use methods on the IDirectorySearch interface to make paged queries against the domain. For more information, see IDirectorySearch::SetSearchPreference and IDirectorySearch::ExecuteSearch. To enumerate trusted domains, call the LsaEnumerateTrustedDomainsEx function.

Examples

The following code sample demonstrates how to return group account information using a call to the NetQueryDisplayInformation function. If the user specifies a server name, the sample first calls the MultiByteToWideChar function to convert the name to Unicode. The sample calls NetQueryDisplayInformation, specifying information level 3 (NET_DISPLAY_GROUP) to retrieve group account information. If there are entries to return, the sample returns the data and prints the group information. Finally, the code sample frees the memory allocated for the information buffer.


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


Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Lmaccess.h (include Lm.h)

Library

Netapi32.lib

DLL

Netapi32.dll

See also

Network Management Overview
Network Management Functions
Get Functions
LsaEnumerateTrustedDomains
LsaEnumerateTrustedDomainsEx
NET_DISPLAY_GROUP
NET_DISPLAY_MACHINE
NET_DISPLAY_USER
NetGetDisplayInformationIndex
NetUserEnum
NetGroupEnum

 

 

Community Additions

ADD
Show:
© 2014 Microsoft