NetGroupEnum 函式 (lmaccess.h)

發行項
08/24/2023

NetGroupEnum函式會擷取安全性資料庫中每個全域群組的相關資訊，也就是安全性帳戶管理員 (SAM) 資料庫，或者，如果是網域控制站，則為 Active Directory。

NetQueryDisplayInformation函式提供有效機制來列舉全域群組。可能的話，建議您使用 NetQueryDisplayInformation 而不是 NetGroupEnum 函式。

語法

NET_API_STATUS NET_API_FUNCTION NetGroupEnum(
  [in]      LPCWSTR    servername,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resume_handle
);

參數

[in] servername

常數位符串的指標，指定函式執行所在遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。

[in] level

指定資料的資訊層級。此參數可以是下列其中一個值。

值	意義
0	傳回通用群組名。 bufptr參數指向GROUP_INFO_0結構的陣列。
1	傳回通用群組名和批註。 bufptr參數指向GROUP_INFO_1結構的陣列。
2	傳回全域群組的詳細資訊。 bufptr參數指向GROUP_INFO_2結構的陣列。請注意，在 Windows XP 和更新版本上，建議您改用 GROUP_INFO_3 。
3	傳回全域群組的詳細資訊。 bufptr參數指向GROUP_INFO_3結構的陣列。 Windows 2000：不支援此層級。

[out] bufptr

要接收全域群組資訊結構的緩衝區指標。此資料的格式取決於 level 參數的值。

系統會為此緩衝區配置記憶體。您必須呼叫 NetApiBufferFree 函式來解除配置記憶體。請注意，即使函式因ERROR_MORE_DATA而失敗，您仍必須釋放緩衝區。

[in] prefmaxlen

指定所傳回資料的慣用最大長度，以位元組為單位。如果您指定MAX_PREFERRED_LENGTH，函式會配置保存資料所需的記憶體數量。如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。如果緩衝區大小不足以保存所有專案，函式會傳回ERROR_MORE_DATA。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理函式緩衝區長度。

[out] entriesread

值指標，這個值會接收實際列舉的專案計數。

[out] totalentries

值的指標，這個值會接收可能已從目前繼續位置列舉的專案總數。專案總數只是提示。如需判斷確切專案數目的詳細資訊，請參閱下列一節。

[in, out] resume_handle

變數的指標，其中包含用來繼續全域群組列舉的繼續控制碼。第一次呼叫時，控制碼應該是零，後續呼叫則保持不變。如果此參數為 Null，則不會儲存任何繼續控制碼。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	描述
ERROR_ACCESS_DENIED	使用者無法存取要求的資訊。
NERR_InvalidComputer	電腦名稱無效。
ERROR_MORE_DATA	有更多專案可供使用。指定夠大的緩衝區來接收所有專案。

備註

如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的功能，方法是呼叫網路管理群組函式。如需詳細資訊，請參閱 IADsGroup。

如果您在執行 Active Directory 的網域控制站上呼叫此函式，則會根據安全性實體物件的存取控制清單 (ACL) ，允許或拒絕存取。預設 ACL 允許「Windows 2000 前相容存取」群組的所有已驗證使用者和成員檢視資訊。如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。如需匿名存取和限制這些平臺上匿名存取的資訊，請參閱網路管理功能的安全性需求。如需 ACL、ACE 和存取權杖的詳細資訊，請參閱存取控制模型。

函式只會傳回呼叫端具有讀取權限的資訊。呼叫端必須具有 Domain 物件的清單內容存取權，並在位於系統容器的 SAM Server 物件上列舉整個 SAM 網域存取權。

若要判斷群組的確切總數，您必須列舉整個樹狀結構，這可以是成本高昂的作業。若要列舉整個樹狀結構，請使用 resume_handle 參數繼續連續呼叫的列舉，並使用 entriesread 參數累積群組總數。如果您的應用程式與網域控制站通訊，您應該考慮使用 ADSI LDAP 提供者，更有效率地擷取這種類型的資料。 ADSI LDAP 提供者會實作一組支援各種 ADSI 介面的 ADSI 物件。如需詳細資訊，請參閱 ADSI 服務提供者。

使用者帳戶名稱限制為 20 個字元，且組名限制為 256 個字元。此外，帳戶名稱不能以句號終止，而且不能包含逗號或任何下列可列印字元：「、/、、[、]、：、|、 <> +、=、;、？、*。名稱也無法在範圍 1-31 中包含不可列印的字元。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	lmaccess.h (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll