TreeSetNamedSecurityInfoA-Funktion (aclapi.h)

Artikel
02/26/2024

Diese Version dieser Funktion wird nicht unterstützt. Die Breitzeichenversion dieser Funktion, TreeSetNamedSecurityInfoW, wird unterstützt.

Syntax

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

Parameter

[in] pObjectName

Zeiger auf eine NULL-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-Enumeration , der den Typ des Objekts mit dem pObjectName-Parameter angibt. Die unterstützten Werte sind SE_REGISTRY_KEY und SE_FILE_OBJECT für Registrierungsschlüssel bzw. Dateiobjekte.

[in] SecurityInfo

Eine Reihe von Bitflags, die den Typ der festzulegenden Sicherheitsinformationen angeben. Dieser Parameter kann eine Kombination der SECURITY_INFORMATION Bitflags 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 einer Sicherheitsbeschreibung zugewiesen werden kann. Der SecurityInfo-Parameter muss das OWNER_SECURITY_INFORMATION-Flag enthalten. Um den Besitzer festzulegen, muss der Aufrufer WRITE_OWNER Zugriff auf jedes Objekt haben, 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 SecurityInfo-Parameter muss das GROUP_SECURITY_INFORMATION-Flag enthalten. Um die Gruppe festzulegen, muss der Aufrufer WRITE_OWNER Zugriff auf jedes Objekt haben, einschließlich des Stammobjekts. Wenn Sie die primäre Gruppen-SID nicht festlegen, kann dieser Parameter NULL sein.

[in, optional] pDacl

Ein Zeiger auf eine ACL-Struktur ( Access Control List ), die die neue DACL für die zurückgesetzten Objekte darstellt. Der SecurityInfo-Parameter muss das flag DACL_SECURITY_INFORMATION enthalten. Der Aufrufer muss READ_CONTROL und WRITE_DAC Zugriff auf jedes Objekt haben, 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 SecurityInfo-Parameter 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 das SE_SECURITY_NAME-Recht für den Aufrufer aktiviert sein. 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 entweder im pDacl - oder pSacl-Parameter angegeben werden, werden die Sicherheitsbeschreibungen dem -Objekt zugeordnet. Die Sicherheitsbeschreibungen 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 der Sicherheitsbeschreibung für das Objekt erteilt, wird die Weitergabe von Sicherheitsinformationen auf diesem bestimmten Knoten der Struktur und den zugehörigen Objekten übersprungen. Der Vorgang wird für den Rest der Struktur unter dem objekt fortgesetzt, das durch den pObjectName-Parameter angegeben wird.
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, bleiben unverändert. Wenn ein Objekt in der Struktur dem Aufrufer keine entsprechenden Berechtigungen zum Ändern der Sicherheitsbeschreibung für das Objekt erteilt, wird die Weitergabe von Sicherheitsinformationen auf diesem bestimmten Knoten der Struktur und den zugehörigen Objekten übersprungen. Der Vorgang wird für den Rest der Struktur unter dem objekt fortgesetzt, das durch den pObjectName-Parameter angegeben wird.

[in] fnProgress

Ein Zeiger auf die Funktion, die zum Nachverfolgen des Fortschritts der TreeSetNamedSecurityInfo-Funktion verwendet wird. Der Prototyp der Fortschrittsfunktion ist:

#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 Fortschritts- und Fehlerinformationen bereit, wenn Knoten verarbeitet werden. Der Aufrufer gibt die Statusfunktion in fnProgress an, und während des Strukturvorgangs übergibt TreeSetNamedSecurityInfo den Namen des zuletzt verarbeiteten Objekts, den Fehler status dieses Vorgangs und den aktuellen PROG_INVOKE_SETTING Wert. Der Aufrufer kann den wert der PROG_INVOKE_SETTING 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-Enumeration , der die anfängliche Einstellung für die Statusfunktion angibt.

[in, optional] Args

Ein Zeiger auf die vom Aufrufer angegebenen VOID for progress-Funktionsargumente.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ERROR_SUCCESS zurück.

Wenn die Funktion fehlschlägt, gibt sie einen in WinError.h definierten Fehlercode zurück.

Hinweise

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

Wenn der Aufrufer nicht die richtigen Berechtigungen und Berechtigungen zur Unterstützung der angeforderten Besitzer-, Gruppen-, DACL- und SACL-Updates enthält, wird keines der Updates ausgeführt.

Diese Funktion bietet die gleiche Funktionalität wie die SetNamedSecurityInfo-Funktion , wenn der Wert des dwAction-Parameters auf TREE_SEC_INFO_SET festgelegt ist, der Wert des ProgressInvokeSetting-Parameters auf ProgressInvokePrePostError festgelegt ist und die Funktion, auf die vom fnProgress-Parameter verwiesen wird, den Wert des pInvokeSetting-Parameters auf ProgressInvokePrePostError festlegt.

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 KeepExplicit-Parameter auf TRUE festgelegt ist.
Wenn der dwAction-Parameter von TreeSetNamedSecurityInfo auf TREE_SEC_INFO_RESET festgelegt ist, entspricht die Funktion TreeResetNamedSecurityInfo , wobei der KeepExplicit-Parameter auf FALSE festgelegt ist.

Hinweis

Der aclapi.h-Header definiert TreeSetNamedSecurityInfo als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	aclapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll