NetUserGetGroups 函式 (lmaccess.h)

發行項
08/24/2023

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

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

值	意義
0	傳回使用者所屬的全域群組名稱。 bufptr參數指向GROUP_USERS_INFO_0結構的陣列。
1	傳回使用者與屬性所屬的全域群組名稱。 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。

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

傳回碼	描述
ERROR_ACCESS_DENIED	使用者沒有所要求資訊的存取權限。
ERROR_BAD_NETPATH	找不到網路路徑。如果找不到 servername 參數，就會傳回此錯誤。
ERROR_INVALID_LEVEL	系統呼叫層級不正確。如果層級參數指定為 0 或 1 以外的值，就會傳回此錯誤。
ERROR_INVALID_NAME	名稱語法不正確。如果 servername 參數的開頭或尾端空白或包含不合法的字元，就會傳回此錯誤。
ERROR_MORE_DATA	有更多專案可供使用。指定足夠的緩衝區來接收所有專案。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成作業。
NERR_InternalError	發生內部錯誤。
NERR_UserNotFound	找不到使用者。如果找不到使用者名稱，就會傳回此錯誤。

備註

如果您要針對 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