NetQueryDisplayInformation

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

Security Requirements

No special group membership is required to successfully execute NetQueryDisplayInformation.

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

Parameters

ServerName

Pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

Level

Specifies one of the following values to return the level of information provided.

Value	Meaning
1	Return all Local and Global (normal) user accounts. The returned buffer points to an array of NET_DISPLAY_USER structures.
2	Return all Workstation and Server (BDC) user accounts. The returned buffer points to an array of NET_DISPLAY_MACHINE structures.
3	Return all Global Groups. The returned buffer points to an array of NET_DISPLAY_GROUP structures.

Index

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. If a call to NetQueryDisplayInformation returns ERROR_MORE_DATA, you can set Index to the value returned in the next_index member of the last entry in SortedBuffer to get data for additional entries. To retrieve information for entries beginning with a specified prefix, set Index to the index returned by a call to the NetGetDisplayInformationIndex function.

EntriesRequested

Specifies the maximum number of entries for which to get information.

PreferredMaximumLength

Specifies the preferred maximum size, in 8-bit bytes, of the system-allocated buffer returned in the SortedBuffer parameter.

ReturnedEntryCount

Pointer to a 32-bit variable that receives the number of entries in the buffer returned in the SortedBuffer parameter. Zero indicates that 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

Points to a variable that receives a pointer to a system-allocated buffer containing a sorted list of the requested information. This buffer contains an array of NET_DISPLAY_USER, NET_DISPLAY_MACHINE or NET_DISPLAY_GROUP structures. Use NetApiBufferFree to deallocate the buffer.

Return Values

If the function returns account information, the return value is one of the following values.

Value	Meaning
NERR_Success	There are no more entries to be returned.
ERROR_MORE_DATA	More entries are available. That is, the last entry returned in the SortedBuffer parameter is not the last entry available. To get information for 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.

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

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.

Remarks

The NetQueryDisplayInformation and NetGetDisplayInformationIndex functions provide a very efficient mechanism for enumerating User and Global group accounts. When possible, use these functions instead of the NetUserEnum and NetGroupEnum functions.

QuickInfo