| Platform SDK: Network Management |
The NetQueryDisplayInformation function returns user account, computer, or group account information. Call this function to quickly enumerate account information for display in user interfaces.
Windows NT: No special group membership is required to successfully execute the NetQueryDisplayInformation function.
Windows 2000: If you call this function on a Windows 2000 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. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.
If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.
For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.
NET_API_STATUS NetQueryDisplayInformation( LPCWSTR ServerName, DWORD Level, DWORD Index, DWORD EntriesRequested, DWORD PreferredMaximumLength, LPDWORD ReturnedEntryCount, PVOID *SortedBuffer );
| Value | Meaning |
|---|---|
| 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. |
If the function succeeds, the return value is NERR_Success.
If the function fails, the return value is one of the following error codes.
| Value | Meaning |
|---|---|
| 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. |
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.
Windows 2000: Calling the NetQueryDisplayInformation function to enumerate account information on a Windows 2000 domain 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.
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 in chunks of 25 bytes (for demonstration purposes) and prints the group information. Finally, the code sample frees the memory allocated for the information buffer.
#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>
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).
// This code returns the data in chunks of 25 bytes to
// demonstrate how to make the request over and over again.
//
res = NetQueryDisplayInformation(szServer, 3, i, 1000, 25, &dwRec, &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"
"Attributs: %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 NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.
Network Management Overview, Network Management Functions, Get Functions, NET_DISPLAY_GROUP, NET_DISPLAY_MACHINE, NET_DISPLAY_USER, NetGetDisplayInformationIndex, NetUserEnum, NetGroupEnum