TreeSetNamedSecurityInfoA 函式 (aclapi.h)

不支援此函式的這個版本。 支援此函式的寬字元版本 TreeSetNamedSecurityInfoW。

語法

DWORD TreeSetNamedSecurityInfoA(
  [in]           LPSTR                pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 pOwner,
  [in, optional] PSID                 pGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl,
  [in]           DWORD                dwAction,
  [in]           FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

參數

[in] pObjectName

Null 終止字串的指標，指定要接收更新安全性資訊之物件的根節點物件名稱。 支援的對象是登錄機碼和檔案物件。 如需不同物件類型的字串格式描述，請參閱 SE_OBJECT_TYPE。

[in] ObjectType

SE_OBJECT_TYPE列舉的值，指出 pObjectName 參數所命名的物件類型。 針對登錄機碼和檔案對象，支援的值為SE_REGISTRY_KEY和SE_FILE_OBJECT。

[in] SecurityInfo

一組位旗標，表示要設定的安全性信息類型。 這個參數可以是 SECURITY_INFORMATION 位旗標的組合。

[in, optional] pOwner

識別物件擁有者 之 SID 結構的指標。 SID 必須是可指派為安全描述元擁有者 SID 的 SID。 SecurityInfo 參數必須包含OWNER_SECURITY_INFORMATION旗標。 若要設定擁有者，呼叫端必須具有每個物件的WRITE_OWNER存取權，包括根物件。 如果您未設定擁有者 SID，此參數可以是 NULL。

[in, optional] pGroup

識別物件主要群組之 SID 結構的指標。 SecurityInfo 參數必須包含GROUP_SECURITY_INFORMATION旗標。 若要設定群組，呼叫端必須具有每個物件的WRITE_OWNER存取權，包括根物件。 如果您未設定主要群組 SID，此參數可以是 NULL。

[in, optional] pDacl

訪問控制清單的指標， (ACL) 結構，代表要重設之物件的新 DACL。 SecurityInfo 參數必須包含DACL_SECURITY_INFORMATION旗標。 呼叫端必須具有每個物件的READ_CONTROL和WRITE_DAC存取權，包括根物件。 如果您未設定 DACL，此參數可以是 NULL。

[in, optional] pSacl

ACL 結構的指標，表示要重設之物件的新 SACL。 SecurityInfo 參數必須包含下列任何旗標：SACL_SECURITY_INFORMATION、LABEL_SECURITY_INFORMATION、ATTRIBUTE_SECURITY_INFORMATION、SCOPE_SECURITY_INFORMATION或BACKUP_SECURITY_INFORMATION。 如果設定SACL_SECURITY_INFORMATION或SCOPE_SECURITY_INFORMATION，則呼叫端必須啟用SE_SECURITY_NAME許可權。 如果您未設定 SACL，此參數可以是 NULL。

[in] dwAction

指定此函式的行為。 這必須設定為下列其中一個值，定義於 AccCtrl.h 中。

[in] fnProgress

用來追蹤 TreeSetNamedSecurityInfo 函式進度之函式的指標。 進度函式的原型為：

#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

typedef VOID (*FN_PROGRESS) (
  IN LPWSTR pObjectName,              // Name of object just processed
  IN DWORD Status,                    // Status of operation on object
  IN OUT PPROG_INVOKE_SETTING
                      pInvokeSetting, // When to set
  IN PVOID Args,                      // Caller specific data
  IN BOOL SecuritySet                 // Whether security was set
);

progress 函式會在處理節點時，提供呼叫端的進度和錯誤資訊。 呼叫端會在 fnProgress 中指定進度函式，並在樹狀結構作業期間 ，TreeSetNamedSecurityInfo 會傳遞最後處理的物件名稱、該作業的錯誤狀態，以及目前的PROG_INVOKE_SETTING值。 呼叫端可以使用 pInvokeSetting 來變更PROG_INVOKE_SETTING值。

如果未使用任何進度函式，請將此參數設定為 NULL。

[in] ProgressInvokeSetting

指定進度函式初始設定 的 PROG_INVOKE_SETTING 列舉值。

[in, optional] Args

VOID 的指標，用於呼叫端所指定的進度函式自變數。

傳回值

如果函式成功，函式會傳回 ERROR_SUCCESS。

如果函式失敗，它會傳回 WinError.h 中定義的錯誤碼。

備註

此函式不支援設定 NULL 擁有者、群組、DACL 或 SACL。

如果呼叫端未包含支援所要求擁有者、群組、DACL 和 SACL 更新的適當許可權和許可權，則不會執行任何更新。

當 dwAction 參數的值設定為 TREE_SEC_INFO_SET、ProgressInvokeSetting 參數的值設定為 ProgressInvokePrePostError 時，此函式會提供與 SetNamedSecurityInfo 函式相同的功能，而 fnProgress 參數所指向的函式會將其 pInvokeSetting 參數的值設定為 ProgressInvokePrePostError。

此函式類似於 TreeResetNamedSecurityInfo 函式：

• 如果 TreeSetNamedSecurityInfo 的 dwAction 參數設定為 TREE_SEC_INFO_RESET_KEEP_EXPLICIT，則函式相當於 TreeResetNamedSecurityInfo，並將 KeepExplicit 參數設定為 TRUE。
• 如果 TreeSetNamedSecurityInfo 的 dwAction 參數設定為 TREE_SEC_INFO_RESET，則函式相當於 TreeResetNamedSecurityInfo，並將 KeepExplicit 參數設定為 FALSE。

規格需求