Fonction ConvertSecurityDescriptorToStringSecurityDescriptorA (sddl.h)

Article
03/01/2024

La fonction ConvertSecurityDescriptorToStringSecurityDescriptor convertit un descripteur de sécurité en format de chaîne. Vous pouvez utiliser le format de chaîne pour stocker ou transmettre le descripteur de sécurité.

Pour convertir le descripteur de sécurité au format chaîne en descripteur de sécurité valide et fonctionnel, appelez la fonction ConvertStringSecurityDescriptorToSecurityDescriptor .

Syntaxe

BOOL ConvertSecurityDescriptorToStringSecurityDescriptorA(
  [in]  PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]  DWORD                RequestedStringSDRevision,
  [in]  SECURITY_INFORMATION SecurityInformation,
  [out] LPSTR                *StringSecurityDescriptor,
  [out] PULONG               StringSecurityDescriptorLen
);

Paramètres

[in] SecurityDescriptor

Pointeur vers le descripteur de sécurité à convertir. Le descripteur de sécurité peut être au format absolu ou auto-relatif.

[in] RequestedStringSDRevision

Spécifie le niveau de révision de la chaîne StringSecurityDescriptor de sortie. Actuellement, cette valeur doit être SDDL_REVISION_1.

[in] SecurityInformation

Spécifie une combinaison des indicateurs de bits SECURITY_INFORMATION pour indiquer les composants du descripteur de sécurité à inclure dans la chaîne de sortie.

L’indicateur BACKUP_SECURITY_INFORMATION n’est pas applicable à cette fonction. Si l’indicateur BACKUP_SECURITY_INFORMATION est passé, le paramètre SecurityInformation retourne TRUE avec une sortie de chaîne null .

[out] StringSecurityDescriptor

Pointeur vers une variable qui reçoit un pointeur vers une chaîne de descripteur de sécurité terminée par null. Pour obtenir une description du format de chaîne, consultez Security Descriptor String Format. Pour libérer la mémoire tampon retournée, appelez la fonction LocalFree .

[out] StringSecurityDescriptorLen

Pointeur vers une variable qui reçoit la taille, en TCHAR, de la chaîne de descripteur de sécurité retournée dans la mémoire tampon StringSecurityDescriptor . Ce paramètre peut être NULL si vous n’avez pas besoin de récupérer la taille. La taille représente la taille de la mémoire tampon dans les WCHAR, et non le nombre de WCHARdans la chaîne.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. La fonction GetLastError peut retourner l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_INVALID_PARAMETER	Un paramètre n'est pas valide.
ERROR_UNKNOWN_REVISION	Le niveau de révision n’est pas valide.
ERROR_NONE_MAPPED	Un identificateur de sécurité (SID) dans le descripteur de sécurité d’entrée est introuvable dans une opération de recherche de compte.
ERROR_INVALID_ACL	La liste de contrôle d’accès (ACL) n’est pas valide. Cette erreur est retournée si l’indicateur SE_DACL_PRESENT est défini dans le descripteur de sécurité d’entrée et si la liste DACL a la valeur NULL.

Remarques

Si la liste DACL a la valeur NULL et que le bit de contrôle SE_DACL_PRESENT est défini dans le descripteur de sécurité d’entrée, la fonction échoue.

Si la liste DACL a la valeur NULL et que le bit de contrôle SE_DACL_PRESENT n’est pas défini dans le descripteur de sécurité d’entrée, la chaîne de descripteur de sécurité résultante n’a pas de composant D :. Pour plus d’informations, consultez Format de chaîne de descripteur de sécurité.

Notes

L’en-tête sddl.h définit ConvertSecurityDescriptorToStringSecurityDescriptor 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. La combinaison 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	sddl.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll