ConvertSecurityDescriptorToStringSecurityDescriptorW, fonction (sddl.h)

Article
11/20/2024

La fonction ConvertSecurityDescriptorToStringSecurityDescriptor convertit un descripteur de sécurité au 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 ConvertSecurityDescriptorToStringSecurityDescriptorW(
  [in]  PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]  DWORD                RequestedStringSDRevision,
  [in]  SECURITY_INFORMATION SecurityInformation,
  [out] LPWSTR               *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 autodéclaré .

[in] RequestedStringSDRevision

Spécifie le niveau de révision de la sortie StringSecurityDescriptor chaîne. 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 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é null-terminated security. Pour obtenir une description du format de chaîne, consultez Format de chaîne de descripteur de sécurité. Pour libérer la mémoire tampon retournée, appelez la fonction LocalFree.

[out] StringSecurityDescriptorLen

Pointeur vers une variable qui reçoit la taille, dans TCHARs, 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 WCHAR, et non le nombre de WCHAR dans la chaîne.

Valeur de retour

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’erreur étendues, appelez GetLastError. La fonction GetLastError peut retourner l’un des codes d’erreur suivants.

Retourner le code	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	Impossible de trouver un identificateur de sécurité (SID) dans le descripteur de sécurité d’entrée 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 de SE_DACL_PRESENT est défini dans le descripteur de sécurité d’entrée et si le dacl est null.

Remarques

Si la liste DACL est 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 est 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é.

Note

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