NetUserGetLocalGroups 函式 (lmaccess.h)
NetUserGetLocalGroups函式會擷取指定使用者所屬的本機群組清單。
語法
NET_API_STATUS NET_API_FUNCTION NetUserGetLocalGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] DWORD flags,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
參數
[in] servername
常數位符串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。 如果此參數為 Null，則會使用本機電腦。
[in] username
常數位符串的指標，指定要傳回本機群組成員資格資訊的使用者名稱。 如果字串的格式為DomainName UserName\ ，則預期在該網域上可以找到使用者名稱。 如果字串的格式為 UserName，預期會在 servername 參數所指定的伺服器上找到使用者名稱。 如需詳細資訊，請參閱＜備註＞一節。
[in] level
資料的資訊層級。 此參數可以是下列值。
| 值 | 意義 |
|---|---|
|
傳回使用者所屬的本機群組名稱。 bufptr參數指向LOCALGROUP_USERS_INFO_0結構的陣列。 |
[in] flags
影響作業之旗標的位元遮罩。 目前，只有定義的值 LG_INCLUDE_INDIRECT。 如果設定此位，此函式也會傳回使用者間接成為成員 (的本機群組名稱，也就是使用者在屬於一或多個本機群組成員的全域群組中具有成員資格) 。
[out] bufptr
接收資料的緩衝區指標。 此資料的格式取決於 level 參數的值。 此緩衝區是由系統所配置，必須使用 NetApiBufferFree 函式釋放。 請注意，即使函式因 ERROR_MORE_DATA而失敗，您仍必須釋放緩衝區。
[in] prefmaxlen
所傳回資料的慣用最大長度，以位元組為單位。 如果在此參數中指定 MAX_PREFERRED_LENGTH ，函式會配置資料所需的記憶體數量。 如果此參數中指定了另一個值，它可以限制函式傳回的位元組數目。 如果緩衝區大小不足以保存所有專案，函式會 傳回ERROR_MORE_DATA。 如需詳細資訊，請參閱 網路管理功能緩衝區 和 網路管理函式緩衝區長度。
[out] entriesread
值指標，可接收實際列舉的專案計數。
[out] totalentries
值的指標，接收可能已列舉的專案總數。
傳回值
如果函式成功，傳回值會NERR_Success。
如果函式失敗，傳回值可以是下列其中一個錯誤碼。
| 傳回碼 | 描述 |
|---|---|
|
使用者沒有所要求資訊的存取權限。 如果 servername 參數的尾端空白，也會傳回此錯誤。 |
|
系統呼叫層級不正確。 如果未將 level 參數指定為 0，則會傳回此錯誤。 |
|
參數不正確。 如果 flags 參數包含 LG_INCLUDE_INDIRECT以外的值，就會傳回此錯誤。 |
|
有更多專案可供使用。 指定夠大的緩衝區來接收所有專案。 |
|
記憶體不足，無法完成作業。 |
|
找不到網域控制站。 |
|
找不到使用者。 如果找不到 使用者名稱 ，則會傳回此錯誤。 |
|
RPC 伺服器無法使用。 如果找不到 servername 參數，則會傳回此錯誤。 |
備註
如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的功能，方法是呼叫網路管理使用者函式。 如需詳細資訊，請參閱 IADsUser 和 IADsComputer。
如果您在執行 Active Directory 的網域控制站上呼叫此函式，則會根據 安全性實體物件的存取控制清單 (ACL) ，允許或拒絕存取。 預設 ACL 允許「Windows 2000 前相容存取」群組的所有已驗證使用者和成員檢視資訊。 如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。 如需匿名存取和限制這些平臺上匿名存取的資訊，請參閱 網路管理功能的安全性需求。 如需 ACL、ACE 和存取權杖的詳細資訊，請參閱存取控制模型。
Domain 物件的安全性描述項是用來執行此函式的存取檢查。 呼叫端在 Domain 物件上必須具有 Read Property 許可權。
若要擷取指定使用者所屬的全域群組清單，您可以呼叫 NetUserGetGroups 函 式。
使用者帳戶名稱限制為 20 個字元，且組名限制為 256 個字元。 此外，帳戶名稱不能以句號終止，而且不能包含逗號或任何下列可列印字元：「、/、、[、]、：、|、 <> +、=、;、？、*。 名稱也無法在範圍 1-31 中包含不可列印的字元。
範例
下列程式碼範例示範如何使用 對 NetUserGetLocalGroups 函式的呼叫，擷取使用者所屬的本機群組清單。 此範例會呼叫 NetUserGetLocalGroups，並指定資訊層級 0 (LOCALGROUP_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[])
{
LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwFlags = LG_INCLUDE_INDIRECT ;
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 NetUserGetLocalGroups function
// specifying information level 0.
//
// The LG_INCLUDE_INDIRECT flag specifies that the
// function should also return the names of the local
// groups in which the user is indirectly a member.
//
nStatus = NetUserGetLocalGroups(argv[1],
argv[2],
dwLevel,
dwFlags,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nLocal group(s):\n");
//
// Loop through the entries and
// print the names of the local 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->lgrui0_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 memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
需求
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | lmaccess.h (包含 Lm.h) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |