TreeResetNamedSecurityInfoA-Funktion (aclapi.h)

Artikel
11/20/2024

Diese Version dieser Funktion wird nicht unterstützt. Die breite Zeichenversion dieser Funktion, TreeResetNamedSecurityInfoW, wird unterstützt.

Syntax

DWORD TreeResetNamedSecurityInfoA(
  [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]           BOOL                 KeepExplicit,
  [in, optional] 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 Reihe von Bitkennzeichnungen, die den Typ der zurückzusetzenden 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] KeepExplicit

Boolescher Wert, der definiert, ob explizit definierte ACEs für die Unterstruktur beibehalten oder gelöscht werden. Wenn KeepExplicit-TRUEist, werden explizit definierte ACEs für jede Unterstruktur DACL und SACL beibehalten, und geerbte ACEs werden durch die geerbten ACEs von pDacl und pSaclersetzt. Wenn KeepExplicitFALSEist, werden explizit definierte ACEs für jede Unterstruktur DACL und SACL gelöscht, bevor die geerbten ACEs durch die geerbten ACEs von pDacl und pSaclersetzt werden.

[in, optional] fnProgress

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

#include <windows.h>
#include <Aclapi.h>

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 TreeResetNamedSecurityInfo 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_SUCCESS zurü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 ähnelt der TreeSetNamedSecurityInfo Funktion:

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

Anmerkung

Der Header "aclapi.h" definiert TreeResetNamedSecurityInfo 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 XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	aclapi.h
Library	Advapi32.lib
DLL-	Advapi32.dll

Freigeben über