ConvertSecurityDescriptorToStringSecurityDescriptorA-Funktion (sddl.h)

Artikel
08/25/2023

Die ConvertSecurityDescriptorToStringSecurityDescriptor-Funktion konvertiert einen Sicherheitsdeskriptor in ein Zeichenfolgenformat. Sie können das Zeichenfolgenformat verwenden, um den Sicherheitsdeskriptor zu speichern oder zu übertragen.

Um den Sicherheitsdeskriptor im Zeichenfolgenformat wieder in einen gültigen funktionalen Sicherheitsdeskriptor zu konvertieren, rufen Sie die ConvertStringSecurityDescriptorToSecurityDescriptor-Funktion auf.

Syntax

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

Parameter

[in] SecurityDescriptor

Ein Zeiger auf den zu konvertierenden Sicherheitsdeskriptor. Der Sicherheitsdeskriptor kann im absoluten oder selbstrelativen Format vorliegen.

[in] RequestedStringSDRevision

Gibt die Revisionsebene der StringSecurityDescriptor-Ausgabezeichenfolge an. Derzeit muss dieser Wert SDDL_REVISION_1 sein.

[in] SecurityInformation

Gibt eine Kombination der SECURITY_INFORMATION Bitflags an, die die Komponenten des Sicherheitsdeskriptors angeben, die in die Ausgabezeichenfolge eingeschlossen werden sollen.

Das BACKUP_SECURITY_INFORMATION-Flag gilt nicht für diese Funktion. Wenn das BACKUP_SECURITY_INFORMATION-Flag übergeben wird, gibt der SecurityInformation-Parameter TRUE mit einer NULL-Zeichenfolgenausgabe zurück.

[out] StringSecurityDescriptor

Ein Zeiger auf eine Variable, die einen Zeiger auf eine mit NULL endende Sicherheitsdeskriptorzeichenfolge empfängt. Eine Beschreibung des Zeichenfolgenformats finden Sie unter Zeichenfolgenformat für Sicherheitsdeskriptor. Um den zurückgegebenen Puffer freizugeben, rufen Sie die Funktion LocalFree auf .

[out] StringSecurityDescriptorLen

Ein Zeiger auf eine Variable, die die Größe der Sicherheitsdeskriptorzeichenfolge in TCHARsempfängt, die im StringSecurityDescriptor-Puffer zurückgegeben wird. Dieser Parameter kann NULL sein, wenn Sie die Größe nicht abrufen müssen. Die Größe stellt die Größe des Puffers in WCHARs dar, nicht die Anzahl von WCHAR-Sin der Zeichenfolge.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Die GetLastError-Funktion gibt möglicherweise einen der folgenden Fehlercodes zurück.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Ein Parameter ist nicht gültig.
ERROR_UNKNOWN_REVISION	Die Revisionsebene ist ungültig.
ERROR_NONE_MAPPED	Eine Sicherheits-ID (SID) im Eingabesicherheitsdeskriptor konnte in einem Kontosuchvorgang nicht gefunden werden.
ERROR_INVALID_ACL	Die Zugriffssteuerungsliste (Access Control List , ACL) ist ungültig. Dieser Fehler wird zurückgegeben, wenn das flag SE_DACL_PRESENT im Eingabesicherheitsdeskriptor festgelegt ist und die DACL NULL ist.

Hinweise

Wenn die DACL NULL ist und das SE_DACL_PRESENT Kontrollbit im Eingabesicherheitsdeskriptor festgelegt ist, schlägt die Funktion fehl.

Wenn die DACL NULL ist und das SE_DACL_PRESENT Kontrollbit nicht im Eingabesicherheitsdeskriptor festgelegt ist, verfügt die resultierende Sicherheitsdeskriptorzeichenfolge nicht über eine D:-Komponente. Weitere Informationen finden Sie unter Format der Sicherheitsdeskriptorzeichenfolge.

Hinweis

Der sddl.h-Header definiert ConvertSecurityDescriptorToStringSecurityDescriptor als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	sddl.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll