TreeSetNamedSecurityInfoA, fonction (aclapi.h)

Article
11/20/2024

Cette version de cette fonction n’est pas prise en charge. La version large de cette fonction, TreeSetNamedSecurityInfoW, est prise en charge.

Syntaxe

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

Paramètres

[in] pObjectName

Pointeur vers une chaînenull-terminated qui spécifie le nom de l’objet de nœud racine pour les objets qui doivent recevoir des informations de sécurité mises à jour. Les objets pris en charge sont des clés de Registre et des objets de fichier. Pour obtenir des descriptions des formats de chaîne pour les différents types d’objets, consultez SE_OBJECT_TYPE.

[in] ObjectType

Valeur de l’énumération SE_OBJECT_TYPE qui indique le type d’objet nommé par le paramètre pObjectName. Les valeurs prises en charge sont SE_REGISTRY_KEY et SE_FILE_OBJECT, respectivement pour les clés de Registre et les objets de fichier.

[in] SecurityInfo

Ensemble d’indicateurs de bits qui indiquent le type d’informations de sécurité à définir. Ce paramètre peut être une combinaison des indicateurs de bits SECURITY_INFORMATION.

[in, optional] pOwner

Pointeur vers une structure SID qui identifie le propriétaire de l’objet. Le SID doit être celui qui peut être attribué en tant que SID propriétaire d’un descripteur de sécurité. Le paramètre SecurityInfo doit inclure l’indicateur de OWNER_SECURITY_INFORMATION. Pour définir le propriétaire, l’appelant doit avoir WRITE_OWNER accès à chaque objet, y compris l’objet racine. Si vous ne définissez pas le SID propriétaire, ce paramètre peut être NULL.

[in, optional] pGroup

Pointeur vers une structure SID qui identifie le groupe principal de l’objet. Le paramètre SecurityInfo doit inclure l’indicateur de GROUP_SECURITY_INFORMATION. Pour définir le groupe, l’appelant doit avoir WRITE_OWNER accès à chaque objet, y compris l’objet racine. Si vous ne définissez pas le SID du groupe principal, ce paramètre peut être NULL.

[in, optional] pDacl

Pointeur vers une structure de liste de contrôle d’accès (ACL) qui représente la nouvelle liste DACL pour les objets réinitialisés. Le paramètre SecurityInfo doit inclure l’indicateur de DACL_SECURITY_INFORMATION. L’appelant doit avoir READ_CONTROL et WRITE_DAC accès à chaque objet, y compris l’objet racine. Si vous ne définissez pas daCL, ce paramètre peut être NULL.

[in, optional] pSacl

Pointeur vers une structure de liste de contrôle d’accès qui représente la nouvelle liste DE contrôle d’accès pour les objets réinitialisés. Le paramètre SecurityInfo doit inclure l’un des indicateurs suivants : SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION ou BACKUP_SECURITY_INFORMATION. Si vous définissez SACL_SECURITY_INFORMATION ou SCOPE_SECURITY_INFORMATION, l’appelant doit activer le privilège SE_SECURITY_NAME. Si vous ne définissez pas la liste de contrôle d’accès partagé, ce paramètre peut être NULL.

[in] dwAction

Spécifie le comportement de cette fonction. Cette valeur doit être définie sur l’une des valeurs suivantes, définies dans AccCtrl.h.

Valeur	Signification
TREE_SEC_INFO_SET 0x00000001	Les informations de sécurité sont définies sur l’objet spécifié par le paramètre pObjectName et l’arborescence des objets enfants de cet objet. Si les listes de contrôle d’accès sont spécifiées dans les paramètres pDacl ou pSacl, les descripteurs de sécurité sont associés à l’objet. Les descripteurs de sécurité sont propagés à l’arborescence des objets enfants en fonction de leurs propriétés d’héritage.
TREE_SEC_INFO_RESET 0x00000002	Les informations de sécurité sont réinitialisées sur l’objet spécifié par le paramètre pObjectName et l’arborescence des objets enfants de cet objet. Toutes les informations de sécurité existantes sont supprimées de tous les objets de l’arborescence. Si un objet de l’arborescence n’accorde pas les autorisations appropriées à l’appelant pour modifier le descripteur de sécurité sur l’objet, la propagation des informations de sécurité sur ce nœud particulier de l’arborescence et ses objets est ignorée. L’opération se poursuit sur le reste de l’arborescence sous l’objet spécifié par le paramètre pObjectName .
TREE_SEC_INFO_RESET_KEEP_EXPLICIT 0x00000003	Les informations de sécurité sont réinitialisées sur l’objet spécifié par le paramètre pObjectName et l’arborescence des objets enfants de cet objet. Toutes les informations de sécurité héritées existantes sont supprimées de tous les objets de l’arborescence. Les informations de sécurité qui ont été définies explicitement sur les objets de l’arborescence sont inchangées. Si un objet de l’arborescence n’accorde pas les autorisations appropriées à l’appelant pour modifier le descripteur de sécurité sur l’objet, la propagation des informations de sécurité sur ce nœud particulier de l’arborescence et ses objets est ignorée. L’opération se poursuit sur le reste de l’arborescence sous l’objet spécifié par le paramètre pObjectName .

[in] fnProgress

Pointeur vers la fonction utilisée pour suivre la progression de la fonction TreeSetNamedSecurityInfo. Le prototype de la fonction de progression est le suivant :

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

La fonction de progression fournit à l’appelant des informations de progression et d’erreur lorsque les nœuds sont traités. L’appelant spécifie la fonction de progression dans fnProgress, et pendant l’opération d’arborescence, TreeSetNamedSecurityInfo passe le nom du dernier objet traité, l’état d’erreur de cette opération et la valeur PROG_INVOKE_SETTING actuelle. L’appelant peut modifier la valeur de PROG_INVOKE_SETTING à l’aide de pInvokeSetting.

Si aucune fonction de progression n’est à utiliser, définissez ce paramètre sur NULL.

[in] ProgressInvokeSetting

Valeur de l’énumération PROG_INVOKE_SETTING qui spécifie le paramètre initial de la fonction de progression.

[in, optional] Args

Pointeur vers un VOID pour les arguments de fonction de progression spécifiés par l’appelant.

Valeur de retour

Si la fonction réussit, la fonction retourne ERROR_SUCCESS.

Si la fonction échoue, elle retourne un code d’erreur défini dans WinError.h.

Remarques

La définition d’une NULL propriétaire, groupe, DACL ou SACL n’est pas prise en charge par cette fonction.

Si l’appelant ne contient pas les privilèges et autorisations appropriés pour prendre en charge les mises à jour propriétaire, groupe, DACL et SACL demandées, aucune des mises à jour n’est effectuée.

Cette fonction fournit la même fonctionnalité que la fonction SetNamedSecurityInfo lorsque la valeur du paramètre dwAction est définie sur TREE_SEC_INFO_SET, la valeur du paramètre ProgressInvokeSetting est définie sur ProgressInvokePrePostError, et la fonction pointée par le paramètre fnProgress définit la valeur de son paramètre pInvokeSetting sur ProgressInvokePrePostError.

Cette fonction est similaire à la fonction TreeResetNamedSecurityInfo :

Si le paramètre dwAction de TreeSetNamedSecurityInfo est défini sur TREE_SEC_INFO_RESET_KEEP_EXPLICIT, la fonction équivaut à TreeResetNamedSecurityInfo avec le paramètre KeepExplicit défini sur TRUE.
Si le paramètre dwAction de TreeSetNamedSecurityInfo est défini sur TREE_SEC_INFO_RESET, la fonction équivaut à TreeResetNamedSecurityInfo avec le paramètre KeepExplicit défini sur FALSE.

Note

L’en-tête aclapi.h définit TreeSetNamedSecurityInfo comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	aclapi.h
bibliothèque	Advapi32.lib
DLL	Advapi32.dll

Partager via