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.
See Also