NetUserGetGroups 函式 (lmaccess.h)
NetUserGetGroups函式會擷取指定使用者所屬的全域群組清單。
語法
NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
參數
[in] servername
常數位符串的指標，指定要執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。 如果此參數為 Null，則會使用本機電腦。
[in] username
常數位符串的指標，指定要在每個群群組帳戶中搜尋的使用者名稱。 如需詳細資訊，請參閱接下來的＜備註＞一節。
[in] level
要求之資料的資訊層級。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回使用者所屬的全域群組名稱。 bufptr參數指向GROUP_USERS_INFO_0結構的陣列。 |
|
傳回使用者與屬性所屬的全域群組名稱。 bufptr參數指向GROUP_USERS_INFO_1結構的陣列。 |
[out] bufptr
接收資料的緩衝區指標。 此緩衝區是由系統所配置，而且必須使用 NetApiBufferFree 函式釋放。 請注意，即使函式因ERROR_MORE_DATA而失敗，您也必須釋放緩衝區。
[in] prefmaxlen
所傳回資料的慣用最大長度，以位元組為單位。 如果指定MAX_PREFERRED_LENGTH，函式會配置資料所需的記憶體量。 如果此參數中指定了另一個值，它可以限制函式傳回的位元組數目。 如果緩衝區大小不足以保存所有專案，函式會傳回ERROR_MORE_DATA。 如需詳細資訊，請參閱 網路管理功能緩衝區 和 網路管理功能緩衝區長度。
[out] entriesread
值的指標，可接收實際擷取的專案計數。
[out] totalentries
值的指標，接收可能已擷取的專案總數。
傳回值
如果函式成功，傳回值會NERR_Success。
如果函式失敗，傳回值可以是下列其中一個錯誤碼。
| 傳回碼 | 描述 |
|---|---|
|
使用者沒有所要求資訊的存取權限。 |
|
找不到網路路徑。 如果找不到 servername 參數，就會傳回此錯誤。 |
|
系統呼叫層級不正確。 如果 層級 參數指定為 0 或 1 以外的值，就會傳回此錯誤。 |
|
名稱語法不正確。 如果 servername 參數的開頭或尾端空白或包含不合法的字元，就會傳回此錯誤。 |
|
有更多專案可供使用。 指定足夠的緩衝區來接收所有專案。 |
|
記憶體不足，無法完成作業。 |
|
發生內部錯誤。 |
|
找不到使用者。 如果找不到 使用者名稱 ，就會傳回此錯誤。 |
備註
如果您要針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達成相同的功能，方法是呼叫網路管理使用者函式。 如需詳細資訊，請參閱 IADsUser 和 IADsComputer。
如果您在執行 Active Directory 的網域控制站上呼叫此函式，則會根據 安全性實體物件的存取控制清單 (ACL) ，允許或拒絕存取。 預設 ACL 允許所有已驗證的使用者和「Windows 2000 相容存取」群組的成員檢視資訊。 如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。 如需有關匿名存取和限制這些平臺上匿名存取的資訊，請參閱 網路管理功能的安全性需求。 如需 ACL、ACE 和存取權杖的詳細資訊，請參閱存取控制模型。
User 物件的安全性描述元是用來執行此函式的存取檢查。
若要擷取使用者所屬的本機群組清單，您可以呼叫 NetUserGetLocalGroups 函式。 網路群組與 Windows NT 系統群組不同。
使用者帳戶名稱限制為 20 個字元，且組名限制為 256 個字元。 此外，帳戶名稱不能以句號終止，而且不能包含逗號或任何下列可列印字元：「、/、、、[、]、：、| <> 、？、*。 名稱也無法在範圍 1-31 中包含不可列印的字元。
範例
下列程式碼範例示範如何擷取使用者使用 NetUserGetGroups 函式呼叫所屬的全域群組清單。 此範例會呼叫 NetUserGetGroups，並指定資訊層級 0 ( GROUP_USERS_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[])
{
LPGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
NET_API_STATUS nStatus;
if (argc != 3)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
exit(1);
}
//
// Call the NetUserGetGroups function, specifying level 0.
//
nStatus = NetUserGetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nGlobal group(s):\n");
//
// Loop through the entries;
// print the name of the global groups
// to which the user belongs.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
wprintf(L"\t-- %s\n", pTmpBuf->grui0_name);
pTmpBuf++;
dwTotalCount++;
}
}
//
// If all available entries were
// not enumerated, print the number actually
// enumerated and the total number available.
//
if (dwEntriesRead < dwTotalEntries)
fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
//
// Otherwise, just print the total.
//
printf("\nEntries enumerated: %d\n", dwTotalCount);
}
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
需求
| 最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | lmaccess.h (包括 Lm.h) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |