NetUserSetGroups 函式 (lmaccess.h)

發行項
03/09/2023

NetUserSetGroups函式會設定指定使用者帳戶的全域群組成員資格。

語法

NET_API_STATUS NET_API_FUNCTION NetUserSetGroups(
  [in] LPCWSTR servername,
  [in] LPCWSTR username,
  [in] DWORD   level,
  [in] LPBYTE  buf,
  [in] DWORD   num_entries
);

參數

[in] servername

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

[in] username

常數位符串的指標，指定要設定全域群組成員資格的使用者名稱。如需詳細資訊，請參閱＜備註＞一節。

[in] level

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

值	意義
0	buf參數指向指定通用群組名之GROUP_USERS_INFO_0結構的陣列。
1	buf參數指向指定具有屬性之通用群組名之GROUP_USERS_INFO_1結構的陣列。

[in] buf

指定資料的緩衝區指標。如需詳細資訊，請參閱網路管理功能緩衝區。

[in] num_entries

buf參數所指向之陣列中包含的專案數目。

傳回值

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

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

傳回碼	描述
ERROR_ACCESS_DENIED	使用者無法存取要求的資訊。
ERROR_INVALID_LEVEL	系統呼叫層級不正確。如果層級參數指定為 0 或 1 以外的值，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	傳遞的參數無效。如果 num_entries 參數無效，就會傳回此錯誤。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成作業。
NERR_InvalidComputer	電腦名稱無效。
NERR_NotPrimary	只有在網域的主要網域控制站上才允許此作業。
NERR_GroupNotFound	buf參數所指向之GROUP_USERS_INFO_1結構中的GROUP_USERS_INFO_0 grui0_name或grui1_name成員所指定的組名不存在。
NERR_InternalError	發生內部錯誤。
NERR_UserNotFound	找不到使用者名稱。

備註

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

如果您在執行 Active Directory 的網域控制站上呼叫此函式，則會根據安全性實體物件的存取控制清單 (ACL) ，允許或拒絕存取。預設 ACL 只允許網域管理員和帳戶操作員呼叫此函式。在成員伺服器或工作站上，只有系統管理員和 Power Users 可以呼叫此函式。如需詳細資訊，請參閱網路管理功能的安全性需求。如需 ACL、ACE 和存取權杖的詳細資訊，請參閱存取控制模型。

User 物件的安全性描述元是用來執行此函式的存取檢查。

若要授與一個現有全域群組中的使用者成員資格，您可以呼叫 NetGroupAddUser 函式。

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

範例

下列程式碼範例示範如何使用 NetUserSetGroups 函式呼叫來設定使用者帳戶的全域群組成員資格。程式碼範例會填入GROUP_USERS_INFO_0結構grui0_name成員，並呼叫NetUserSetGroups，並指定資訊層級 0。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   GROUP_USERS_INFO_0 gi;
   NET_API_STATUS nStatus;

   if (argc != 4)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName GroupName\n", argv[0]);
      exit(1);
   }
   //
   // Fill in the GROUP_USERS_INFO_0 structure member.
   //
   gi.grui0_name = argv[3];
   //
   // Call the NetUserSetGroups function; specify level 0.
   //
   nStatus = NetUserSetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE)&gi,
                              1);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Group membership has been successful for %s\n", argv[2]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

需求


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