GetNamedSecurityInfoW, fonction (aclapi.h)

Article
11/20/2024

La fonction GetNamedSecurityInfo récupère une copie du descripteur de sécurité pour un objet spécifié par son 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 des descriptions 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. De plus, ce paramètre peut être 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. De plus, ce paramètre peut être 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 DACL dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de daCL. Le pointeur retourné est valide uniquement si vous définissez l’indicateur de DACL_SECURITY_INFORMATION. De plus, ce paramètre peut être 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 liste de contrôle d’accès partagé 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. De plus, ce paramètre peut être NULL si vous n’avez pas besoin de la clé SACL.

[out, optional] ppSecurityDescriptor

Pointeur vers une variable qui reçoit un pointeur vers le descripteur de sécurité de l’objet. Lorsque 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 ppsidOwner, ppsidGroup, ppDaclou paramètres ppSacl n’est pas NULL .

Valeur de retour

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 desppsidOwner , ppsidGroup, ppDaclou paramètres ppSacl ne sont pasNULL, et le paramètre SecurityInfo spécifie qu’ils doivent être 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 daCL à partir du descripteur de sécurité de l’objet, le 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 appelant. Pour plus d’informations sur les implications en matière 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
Clés de Registre
Sémaphores, événements, mutex et minuteurs pouvant être attendus
Objets de mappage de fichiers
Objets de service d’annuaire

Cette fonction ne gère pas les conditions de concurrence. 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 des 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 aucun chiffrement n’est effectué.

Pour plus d’informations sur le contrôle de l’accès aux objets via des comptes d’utilisateur, des comptes de groupe ou des sessions d’ouverture de session, consultez Comment les DACLs contrôlent l’accès à un objet.

Exemples

Pour obtenir un exemple qui utilise GetNamedSecurityInfo, consultez Modification des ACL d’un objet.

Note

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