BuildSecurityDescriptorW, fonction (aclapi.h)

Article
11/20/2024

La fonction BuildSecurityDescriptor alloue et initialise un nouveau descripteur de sécurité . Cette fonction peut initialiser le nouveau descripteur de sécurité en fusionnant les informations de sécurité spécifiées avec les informations d’un descripteur de sécurité existant. Si vous ne spécifiez pas de descripteur de sécurité existant, la fonction initialise un nouveau descripteur de sécurité en fonction des informations de sécurité spécifiées.

La fonction BuildSecurityDescriptor crée un descripteur de sécurité auto-relatif . Le format auto-relatif rend le descripteur de sécurité adapté au stockage dans un flux.

Syntaxe

DWORD BuildSecurityDescriptorW(
  [in, optional] PTRUSTEE_W           pOwner,
  [in, optional] PTRUSTEE_W           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

Paramètres

[in, optional] pOwner

Pointeur vers une structure TRUSTEE qui identifie le propriétaire du nouveau descripteur de sécurité. Si la structure utilise le formulaire TRUSTEE_IS_NAME, BuildSecurityDescriptor recherche l’identificateur de sécurité (SID) associé au nom de l’administrateur spécifié.

Si ce paramètre est null, la fonction utilise le SID propriétaire à partir du descripteur de sécurité d’origine pointé par pOldSD. Si pOldSD est NULL ou si le SID propriétaire dans pOldSD est NULL, le SID propriétaire est NULL dans le nouveau descripteur de sécurité.

[in, optional] pGroup

Pointeur vers une structure TRUSTEE qui identifie le SID de groupe principal pour le nouveau descripteur de sécurité. Si la structure utilise le formulaire TRUSTEE_IS_NAME, BuildSecurityDescriptor recherche le SID associé au nom de fiduciaire spécifié.

Si ce paramètre est null, la fonction utilise le SID de groupe à partir du descripteur de sécurité d’origine pointé par pOldSD. Si pOldSD est NULL ou si le SID de groupe dans pOldSD est NULL, le SID de groupe est NULL dans le nouveau descripteur de sécurité.

[in] cCountOfAccessEntries

Nombre de structures EXPLICIT_ACCESS dans le tableau pListOfAccessEnt ries.

[in, optional] pListOfAccessEntries

Pointeur vers un tableau de structures EXPLICIT_ACCESS qui décrivent les informations de contrôle d’accès pour les liste de contrôle d’accès discrétionnaire (DACL) du nouveau descripteur de sécurité. La fonction crée la nouvelle liste DACL en fusionnant les informations du tableau avec la liste DACL dans pOldSD, le cas échéant. Si pOldSD est NULL ou si la liste DACL dans pOldSD est NULL, la fonction crée une liste DACL basée uniquement sur les informations du tableau. Pour obtenir une description des règles de création d’une liste de contrôle d’accès à partir d’un tableau de structures EXPLICIT_ACCESS, consultez la fonction SetEntriesInAcl .

Si pListOfAccessEntries est NULL, le nouveau descripteur de sécurité obtient la liste dacl de pOldSD. Dans ce cas, si pOldSD est NULL, ou si la liste DACL dans pOldSD est NULL, la nouvelle liste DACL est NULL.

[in] cCountOfAuditEntries

Nombre de structures EXPLICIT_ACCESS dans le tableau pListOfAuditEnt ries.

[in, optional] pListOfAuditEntries

Pointeur vers un tableau de structures EXPLICIT_ACCESS qui décrivent les informations de contrôle d’audit pour la liste de contrôle d’accès partagé du nouveau descripteur de sécurité. La fonction crée la nouvelle liste de contrôle d’accès partagé en fusionnant les informations du tableau avec la liste de contrôle d’accès partagé dans pOldSD, le cas échéant. Si pOldSD est NULL, ou si la liste de contrôle d’accès partagé dans pOldSD est NULL, la fonction crée une clé SACL basée uniquement sur les informations du tableau.

Si pListOfAuditEntries est NULL, le nouveau descripteur de sécurité obtient la liste de contrôle d’accès partagé de pOldSD. Dans ce cas, si pOldSD est NULL, ou si la liste de contrôle d’accès partagé dans pOldSD est NULL, la nouvelle clé SACL est NULL.

[in, optional] pOldSD

Pointeur vers une structure SECURITY_DESCRIPTOR auto-relative existante et ses informations de sécurité associées. La fonction génère le nouveau descripteur de sécurité en fusionnant les informations de propriétaire, de groupe, de contrôle d’accès et de contrôle d’audit spécifiées avec les informations de ce descripteur de sécurité. Ce paramètre peut être NULL.

[out] pSizeNewSD

Pointeur vers une variable qui reçoit la taille, en octets, du descripteur de sécurité.

[out] pNewSD

Pointeur vers une variable qui reçoit un pointeur vers le nouveau descripteur de sécurité. La fonction alloue de la mémoire pour le nouveau descripteur de sécurité. Vous devez appeler la fonction LocalFree pour libérer la mémoire tampon retournée.

Valeur de retour

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

Si la fonction échoue, elle retourne un code d’erreur différent de zéro défini dans WinError.h.

Remarques

La fonction BuildSecurityDescriptor est destinée aux serveurs approuvés qui implémentent ou exposent la sécurité sur leurs propres objets. La fonction utilise des descripteurs de sécurité auto-relatifs adaptés à la sérialisation dans un flux et au stockage sur disque, car un serveur approuvé peut nécessiter.

Note

L’en-tête aclapi.h définit BuildSecurityDescriptor 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 XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	aclapi.h
bibliothèque	Advapi32.lib
DLL	Advapi32.dll