NetUserEnum 函式 (lmaccess.h)
NetUserEnum 函式會擷取伺服器上所有用戶帳戶的相關信息。
語法
NET_API_STATUS NET_API_FUNCTION NetUserEnum(
[in] LPCWSTR servername,
[in] DWORD level,
[in] DWORD filter,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] PDWORD resume_handle
);
參數
[in] servername
常數位符串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。 如果此參數為 NULL，則會使用本機電腦。
[in] level
指定資料的資訊層級。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回用戶帳戶名稱。 bufptr 參數指向USER_INFO_0結構的陣列。 |
|
傳回用戶帳戶的詳細資訊。 bufptr 參數指向USER_INFO_1結構的陣列。 |
|
傳回用戶帳戶的詳細資訊，包括授權層級和登入資訊。 bufptr 參數指向USER_INFO_2 結構的陣列。 |
|
傳回使用者帳戶的詳細資訊，包括授權等級、登入資訊、使用者和主要群組的 RID，以及配置檔資訊。 bufptr 參數指向USER_INFO_3結構的陣列。 |
|
傳回用戶和帳戶名稱和批注。 bufptr 參數指向USER_INFO_10結構的陣列。 |
|
傳回用戶帳戶的詳細資訊。 bufptr 參數指向USER_INFO_11 結構的陣列。 |
|
傳回使用者的名稱和標識碼和各種帳戶屬性。 bufptr 參數指向USER_INFO_20結構的陣列。 請注意，在 Windows XP 和更新版本上，建議您改用 USER_INFO_23 。 |
[in] filter
值，指定要包含在列舉中的用戶帳戶類型。 值為零表示應該包含所有一般使用者、信任數據和計算機帳戶數據。
此參數也可以是下列值的組合。
[out] bufptr
接收數據的緩衝區指標。 此數據的格式取決於 level 參數的值。
此數據的緩衝區是由系統所配置，而且應用程式必須呼叫 NetApiBufferFree 函式，以在不再需要傳回的數據時釋放配置的記憶體。 請注意，即使 NetUserEnum 函式因ERROR_MORE_DATA而失敗，您還是必須釋放緩衝區。
[in] prefmaxlen
所傳回數據的慣用最大長度，以位元組為單位。 如果您指定 MAX_PREFERRED_LENGTH，NetUserEnum 函式會配置數據所需的記憶體數量。 如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。 如果緩衝區大小不足以保存所有專案，函式會傳回ERROR_MORE_DATA。 如需詳細資訊，請參閱 網路管理功能緩衝區 和 網路管理函式緩衝區長度。
[out] entriesread
值指標，可接收實際列舉的項目計數。
[out] totalentries
值的指標，接收可能已從目前繼續位置列舉的項目總數。 請注意，應用程式應該只將此值視為提示。 如果您的應用程式與 Windows 2000 或更新版本的域控制器通訊，您應該考慮使用 ADSI LDAP 提供者 更有效率地擷取這種類型的數據。 ADSI LDAP 提供者會實作一組支援各種 ADSI 介面的 ADSI 物件。 如需詳細資訊，請參閱 ADSI 服務提供者。
LAN 管理員： 如果呼叫是執行 LAN Manager 2 的電腦。x，totalentries 參數一律會反映資料庫中專案總數，不論其位於繼續序列中的位置。
[in, out] resume_handle
值的指標，其中包含用來繼續現有用戶搜尋的繼續句柄。 第一次呼叫時，句柄應該是零，後續呼叫則保持不變。 如果此參數為 NULL，則不會儲存任何繼續句柄。
傳回值
如果函式成功，傳回值會NERR_Success。
如果函式失敗，傳回值可以是下列其中一個錯誤碼。
| 傳回碼 | Description |
|---|---|
|
用戶無法存取要求的資訊。 |
|
系統呼叫層級不正確。 如果 level 參數設定為不支援的值，就會傳回此錯誤。 |
|
緩衝區太小而無法包含專案。 未將任何資訊寫入緩衝區。 |
|
電腦名稱無效。 |
|
有更多專案可供使用。 指定夠大的緩衝區來接收所有專案。 |
備註
NetUserEnum 函式會擷取指定遠端伺服器或本機電腦上所有用戶帳戶的相關信息。
NetQueryDisplayInformation 函式可用來快速列舉使用者、計算機或全域組帳戶資訊，以顯示在使用者介面 中。
如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的功能，方法是呼叫網路管理使用者函式。 如需詳細資訊，請參閱 IADsUser 和 IADsComputer。
如果您在執行 Active Directory 的域控制器上呼叫 NetUserEnum 函式，則會根據 安全性實體對象的訪問控制清單 (ACL) ，允許或拒絕存取。 默認 ACL 允許「Windows 2000 前相容存取」群組的所有已驗證使用者和成員檢視資訊。 如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。 如需匿名存取和限制這些平臺上匿名存取的資訊，請參閱 網路管理功能的安全性需求。 如需 ACL、ACE 和存取令牌的詳細資訊，請參閱 存取控制 模型。
NetUserEnum 函式只會傳回呼叫端具有讀取許可權的資訊。 呼叫端必須具有 Domain 物件的清單內容存取權，並在位於系統容器的 SAM Server 物件上列舉整個 SAM 網域存取權。
LsaEnumerateTrustedDomains 或 LsaEnumerateTrustedDomainsEx 函式可用來擷取本地安全機構所信任之網域的名稱和 SID， (LSA) 原則物件。
NetUserEnum 函式不會傳回所有系統使用者。 它只會傳回已透過 對 NetUserAdd 函式呼叫新增的使用者。 不保證會依排序順序傳回用戶清單。
如果您針對 level 參數呼叫 NetUserEnum 函式並指定資訊層級 1、2 或 3，則所擷取的每個結構的密碼成員都會設定為 NULL，以維護密碼安全性。
用戶帳戶名稱限製為 20 個字元，且組名限製為 256 個字元。 此外，帳戶名稱不能以句號終止，而且不能包含逗號或任何下列可列印字元：“、/、、[、]、：、|、<>+、=、;、?、*。 名稱也無法在範圍 1-31 中包含不可列印的字元。
NetUserEnum 函式不支援層級參數 4 和 USER_INFO_4 結構。 NetUserGetInfo 函式支援層級參數 4 和 USER_INFO_4 結構。
範例
下列程式代碼範例示範如何使用 對 NetUserEnum 函式的呼叫，擷取伺服器上用戶帳戶的相關信息。 此範例會呼叫 NetUserEnum，並指定資訊層級 0 (USER_INFO_0) ，只列舉全域用戶帳戶。 如果呼叫成功，程式代碼會迴圈查看專案，並列印每個用戶帳戶的名稱。 最後，程式代碼範例會釋放配置給資訊緩衝區的記憶體，並列印列舉的用戶總數。
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPUSER_INFO_0 pBuf = NULL;
LPUSER_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPTSTR pszServerName = NULL;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
exit(1);
}
// The server is not the default local computer.
//
if (argc == 2)
pszServerName = (LPTSTR) argv[1];
wprintf(L"\nUser account on %s: \n", pszServerName);
//
// Call the NetUserEnum function, specifying level 0;
// enumerate global user account types only.
//
do // begin do
{
nStatus = NetUserEnum((LPCWSTR) pszServerName,
dwLevel,
FILTER_NORMAL_ACCOUNT, // global users
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the name of the user account.
//
wprintf(L"\t-- %s\n", pTmpBuf->usri0_name);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, print the system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
// Continue to call NetUserEnum while
// there are more entries.
//
while (nStatus == ERROR_MORE_DATA); // end do
//
// Check again for allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of users enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | lmaccess.h (包含 Lm.h) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |