GetNamedSecurityInfoW, fonction (aclapi.h)

Article
08/22/2023

La fonction GetNamedSecurityInfo récupère une copie du descripteur de sécurité d’un objet spécifié par nom.

Syntaxe

DWORD GetNamedSecurityInfoW(
  [in]            LPCWSTR              pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Paramètres

[in] pObjectName

Pointeur vers une chaîne terminée par null qui spécifie le nom de l’objet à partir duquel récupérer des informations de sécurité. Pour obtenir une description des formats de chaîne pour les différents types d’objets, consultez SE_OBJECT_TYPE.

[in] ObjectType

Spécifie une valeur de l’énumération SE_OBJECT_TYPE qui indique le type d’objet nommé par le paramètre pObjectName .

[in] SecurityInfo

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

[out, optional] ppsidOwner

Pointeur vers une variable qui reçoit un pointeur vers le SID propriétaire dans le descripteur de sécurité retourné dans ppSecurityDescriptor ou NULL si le descripteur de sécurité n’a pas de SID propriétaire. Le pointeur retourné est valide uniquement si vous définissez l’indicateur OWNER_SECURITY_INFORMATION. En outre, ce paramètre peut avoir la valeur NULL si vous n’avez pas besoin du SID propriétaire.

[out, optional] ppsidGroup

Pointeur vers une variable qui reçoit un pointeur vers le SID du groupe principal dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de SID de groupe. Le pointeur retourné est valide uniquement si vous définissez l’indicateur GROUP_SECURITY_INFORMATION. En outre, ce paramètre peut avoir la valeur NULL si vous n’avez pas besoin du SID de groupe.

[out, optional] ppDacl

Pointeur vers une variable qui reçoit un pointeur vers la liste de contrôle d’accès (DACL) dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de contrôle DACL. Le pointeur retourné est valide uniquement si vous définissez l’indicateur DACL_SECURITY_INFORMATION. En outre, ce paramètre peut avoir la valeur NULL si vous n’avez pas besoin de la liste DACL.

[out, optional] ppSacl

Pointeur vers une variable qui reçoit un pointeur vers la saCL dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de sacl. Le pointeur retourné est valide uniquement si vous définissez l’indicateur SACL_SECURITY_INFORMATION. En outre, ce paramètre peut avoir la valeur NULL si vous n’avez pas besoin de la liste SACL.

[out, optional] ppSecurityDescriptor

Pointeur vers une variable qui reçoit un pointeur vers le descripteur de sécurité de l’objet. Une fois que vous avez terminé d’utiliser le pointeur, libérez la mémoire tampon retournée en appelant la fonction LocalFree .

Ce paramètre est obligatoire si l’un des paramètres ppsidOwner, ppsidGroup, ppDacl ou ppSacl n’est pas NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

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

Remarques

Si l’un des paramètres ppsidOwner, ppsidGroup, ppDacl ou ppSacl n’est pas NULL et que le paramètre SecurityInfo spécifie qu’ils sont récupérés à partir de l’objet, ces paramètres pointent vers les paramètres correspondants dans le descripteur de sécurité retourné dans ppSecurityDescriptor. Si le descripteur de sécurité ne contient pas les informations demandées, le paramètre correspondant est défini sur NULL.

Pour lire le propriétaire, le groupe ou la liste DACL à partir du descripteur de sécurité de l’objet, la liste DACL de l’objet doit accorder à READ_CONTROL l’accès à l’appelant, ou l’appelant doit être le propriétaire de l’objet.

Pour lire la liste de contrôle d’accès système de l’objet, le privilège SE_SECURITY_NAME doit être activé pour le processus d’appel. Pour plus d’informations sur les implications de sécurité de l’activation des privilèges, consultez Exécution avec des privilèges spéciaux.

Vous pouvez utiliser la fonction GetNamedSecurityInfo avec les types d’objets suivants :

Fichiers ou répertoires locaux ou distants sur un système de fichiers NTFS
Imprimantes locales ou distantes
Services Windows locaux ou distants
Partages réseau
les clés de Registre
Sémaphores, événements, mutexes et minuteurs d’attente
Objets de mappage de fichiers
Objets de service d’annuaire

Cette fonction ne gère pas les conditions de course. Si votre thread appelle cette fonction au moment approximatif où un autre thread modifie le descripteur de sécurité de l’objet, cette fonction peut échouer.

Cette fonction transfère les informations en texte clair. Les informations transférées par cette fonction sont signées, sauf si la signature a été désactivée pour le système, mais qu’aucun chiffrement n’est effectué.

Pour plus d’informations sur le contrôle de l’accès aux objets par le biais de comptes d’utilisateur, de comptes de groupe ou de sessions d’ouverture de session, consultez How DACLs Control Access to an Object.

Exemples

Pour obtenir un exemple qui utilise GetNamedSecurityInfo, consultez Modification des listes de contrôle d’accès d’un objet.

Notes

L’en-tête aclapi.h définit GetNamedSecurityInfo comme un 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	aclapi.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll