TreeSetNamedSecurityInfoW-Funktion (aclapi.h)

Artikel
11/20/2024

Die TreeSetNamedSecurityInfo-Funktion legt angegebene Sicherheitsinformationen in der Sicherheitsbeschreibung einer angegebenen Struktur von Objekten fest. Mit dieser Funktion kann eine angegebene diskretionäre Zugriffssteuerungsliste (DACL) oder elemente in der Systemzugriffssteuerungsliste (SACL) in einer gesamten Struktur verteilt werden. Diese Funktion unterstützt eine Rückruffunktion, um den Fortschritt des Strukturvorgangs nachzuverfolgen.

Syntax

DWORD TreeSetNamedSecurityInfoW(
  [in]           LPWSTR               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
);

Parameter

[in] pObjectName

Zeigen Sie auf eine NULL--terminated-Zeichenfolge, die den Namen des Stammknotenobjekts für die Objekte angibt, die aktualisierte Sicherheitsinformationen empfangen sollen. Unterstützte Objekte sind Registrierungsschlüssel und Dateiobjekte. Beschreibungen der Zeichenfolgenformate für die verschiedenen Objekttypen finden Sie unter SE_OBJECT_TYPE.

[in] ObjectType

Ein Wert der SE_OBJECT_TYPE-Aufzählung, die den Typ des Objekts angibt, das vom pObjectName Parameter benannt wird. Die unterstützten Werte sind SE_REGISTRY_KEY und SE_FILE_OBJECT für Registrierungsschlüssel bzw. Dateiobjekte.

[in] SecurityInfo

Eine Gruppe von Bitkennzeichnungen, die den Typ der festzulegenden Sicherheitsinformationen angeben. Dieser Parameter kann eine Kombination aus den SECURITY_INFORMATION Bitkennzeichnungen sein.

[in, optional] pOwner

Ein Zeiger auf eine SID Struktur, die den Besitzer des Objekts identifiziert. Die SID muss eine sein, die als Besitzer-SID eines Sicherheitsdeskriptors zugewiesen werden kann. Der parameter SecurityInfo muss das OWNER_SECURITY_INFORMATION Flag enthalten. Um den Besitzer festzulegen, muss der Aufrufer über WRITE_OWNER Zugriff auf jedes Objekt verfügen, einschließlich des Stammobjekts. Wenn Sie die Besitzer-SID nicht festlegen, kann dieser Parameter NULL-sein.

[in, optional] pGroup

Ein Zeiger auf eine SID Struktur, die die primäre Gruppe des Objekts identifiziert. Der parameter SecurityInfo muss das GROUP_SECURITY_INFORMATION Flag enthalten. Um die Gruppe festzulegen, muss der Aufrufer über WRITE_OWNER Zugriff auf jedes Objekt verfügen, einschließlich des Stammobjekts. Wenn Sie die primäre Gruppen-SID nicht festlegen, kann dieser Parameter NULL-werden.

[in, optional] pDacl

Ein Zeiger auf eine Zugriffssteuerungsliste (ACL)-Struktur, die die neue DACL für die zurückgesetzten Objekte darstellt. Der parameter SecurityInfo muss das DACL_SECURITY_INFORMATION Flag enthalten. Der Aufrufer muss über READ_CONTROL und WRITE_DAC Zugriff auf jedes Objekt verfügen, einschließlich des Stammobjekts. Wenn Sie die DACL nicht festlegen, kann dieser Parameter NULL-sein.

[in, optional] pSacl

Ein Zeiger auf eine ACL-Struktur, die die neue SACL für die zurückgesetzten Objekte darstellt. Der parameter SecurityInfo muss eines der folgenden Flags enthalten: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION oder BACKUP_SECURITY_INFORMATION. Wenn sie SACL_SECURITY_INFORMATION oder SCOPE_SECURITY_INFORMATION festlegen, muss der Aufrufer die SE_SECURITY_NAME Berechtigung aktiviert haben. Wenn Sie die SACL nicht festlegen, kann dieser Parameter NULL-sein.

[in] dwAction

Gibt das Verhalten dieser Funktion an. Dies muss auf einen der folgenden Werte festgelegt werden, die in AccCtrl.h definiert sind.

Wert	Bedeutung
TREE_SEC_INFO_SET 0x00000001	Die Sicherheitsinformationen werden für das objekt festgelegt, das durch den pObjectName Parameter und die Struktur der untergeordneten Objekte dieses Objekts angegeben wird. Wenn ACLs in den parametern pDacl oder pSacl- angegeben werden, werden die Sicherheitsdeskriptoren dem Objekt zugeordnet. Die Sicherheitsdeskriptoren werden basierend auf ihren Vererbungseigenschaften an die Struktur untergeordneter Objekte weitergegeben.
TREE_SEC_INFO_RESET 0x00000002	Die Sicherheitsinformationen werden für das objekt zurückgesetzt, das durch den pObjectName Parameter und die Struktur der untergeordneten Objekte dieses Objekts angegeben wird. Alle vorhandenen Sicherheitsinformationen werden aus allen Objekten in der Struktur entfernt. Wenn ein Objekt in der Struktur dem Aufrufer keine entsprechenden Berechtigungen zum Ändern des Sicherheitsdeskriptors für das Objekt gewährt, wird die Weitergabe von Sicherheitsinformationen für diesen bestimmten Knoten der Struktur und deren Objekte übersprungen. Der Vorgang wird für den Rest der Struktur unter dem durch den pObjectName Parameter angegebenen Objekt fortgesetzt.
TREE_SEC_INFO_RESET_KEEP_EXPLICIT 0x00000003	Die Sicherheitsinformationen werden für das objekt zurückgesetzt, das durch den pObjectName Parameter und die Struktur der untergeordneten Objekte dieses Objekts angegeben wird. Alle vorhandenen geerbten Sicherheitsinformationen werden aus allen Objekten in der Struktur entfernt. Sicherheitsinformationen, die explizit für Objekte in der Struktur festgelegt wurden, sind unverändert. Wenn ein Objekt in der Struktur dem Aufrufer keine entsprechenden Berechtigungen zum Ändern des Sicherheitsdeskriptors für das Objekt gewährt, wird die Weitergabe von Sicherheitsinformationen für diesen bestimmten Knoten der Struktur und deren Objekte übersprungen. Der Vorgang wird für den Rest der Struktur unter dem durch den pObjectName Parameter angegebenen Objekt fortgesetzt.

[in] fnProgress

Ein Zeiger auf die Funktion, mit der der Fortschritt der TreeSetNamedSecurityInfo--Funktion nachverfolgt wird. Der Prototyp der Statusfunktion lautet:

#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
);

Die Statusfunktion stellt dem Aufrufer Status- und Fehlerinformationen bereit, wenn Knoten verarbeitet werden. Der Aufrufer gibt die Statusfunktion in fnProgressan, und während des Strukturvorgangs übergibt TreeSetNamedSecurityInfo den Namen des letzten verarbeiteten Objekts, den Fehlerstatus dieses Vorgangs und den aktuellen PROG_INVOKE_SETTING Wert übergibt. Der Aufrufer kann den PROG_INVOKE_SETTING Wert mithilfe von pInvokeSettingändern.

Wenn keine Statusfunktion verwendet werden soll, legen Sie diesen Parameter auf NULL-fest.

[in] ProgressInvokeSetting

Ein Wert der PROG_INVOKE_SETTING-Aufzählung, die die Anfangseinstellung für die Statusfunktion angibt.

[in, optional] Args

Ein Zeiger auf eine VOID für statusfunktionsargumente, die vom Aufrufer angegeben werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ERROR_SUCCESSzurück.

Wenn die Funktion fehlschlägt, wird ein fehlercode zurückgegeben, der in WinError.h definiert ist.

Bemerkungen

Das Festlegen eines NULL Besitzer, Gruppe, DACL oder SACL wird von dieser Funktion nicht unterstützt.

Wenn der Aufrufer nicht die richtigen Berechtigungen und Berechtigungen enthält, um die angeforderten Besitzer-, Gruppen-, DACL- und SACL-Updates zu unterstützen, werden keine Updates ausgeführt.

Diese Funktion bietet die gleiche Funktionalität wie die SetNamedSecurityInfo Funktion, wenn der Wert des dwAction-Parameters auf TREE_SEC_INFO_SETfestgelegt ist, der Wert des ProgressInvokeSetting-Parameters auf ProgressInvokePrePostError, und die Funktion, auf die der fnProgress Parameter verweist, legt den Wert des pInvokeSetting Parameter auf ProgressInvokePrePostError.

Diese Funktion ähnelt der TreeResetNamedSecurityInfo Funktion:

Wenn der dwAction Parameter von TreeSetNamedSecurityInfo auf TREE_SEC_INFO_RESET_KEEP_EXPLICIT festgelegt ist, entspricht die Funktion TreeResetNamedSecurityInfo, wobei der parameter KeepExplicit auf TRUEfestgelegt ist.
Wenn der dwAction Parameter von TreeSetNamedSecurityInfo- auf TREE_SEC_INFO_RESET festgelegt ist, entspricht die Funktion TreeResetNamedSecurityInfo mit dem parameter KeepExplicit auf FALSEfestgelegt ist.

Anmerkung

Der Header "aclapi.h" definiert TreeSetNamedSecurityInfo als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	aclapi.h
Library	Advapi32.lib
DLL-	Advapi32.dll

Freigeben über