ConvertSecurityDescriptorToStringSecurityDescriptorA-Funktion (sddl.h)

Artikel
11/20/2024

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

Rufen Sie die ConvertStringSecurityDescriptorToSecurityDescriptor-Funktion auf, um den Sicherheitsdeskriptor im Zeichenfolgenformat wieder in einen gültigen, funktionalen Sicherheitsdeskriptor umzuwandeln.

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 Formatsein.

[in] RequestedStringSDRevision

Gibt die Revisionsebene der Ausgabe StringSecurityDescriptor Zeichenfolge an. Derzeit muss dieser Wert SDDL_REVISION_1 werden.

[in] SecurityInformation

Gibt eine Kombination der SECURITY_INFORMATION Bitkennzeichnungen an, um die Komponenten des Sicherheitsdeskriptors anzugeben, die in die Ausgabezeichenfolge eingeschlossen werden sollen.

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

[out] StringSecurityDescriptor

Ein Zeiger auf eine Variable, die einen Zeiger auf eine NULL--terminated-Sicherheitsdeskriptorzeichenfolge empfängt. Eine Beschreibung des Zeichenfolgenformats finden Sie unter Security Descriptor String Format. Rufen Sie zum Freigeben des zurückgegebenen Puffers die funktion LocalFree auf.

[out] StringSecurityDescriptorLen

Ein Zeiger auf eine Variable, die die Größe in TCHAR-s der sicherheitsdeskriptorzeichenfolge empfängt, die im StringSecurityDescriptor Puffer zurückgegeben wird. Dieser Parameter kann NULL- werden, wenn Sie die Größe nicht abrufen müssen. Die Größe stellt die Größe des Puffers in WCHARs dar, nicht die Anzahl der WCHARs in der Zeichenfolge.

Rückgabewert

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

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten. Die GetLastError--Funktion kann einen der folgenden Fehlercodes zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Ein Parameter ist ungültig.
ERROR_UNKNOWN_REVISION	Die Revisionsebene ist ungültig.
ERROR_NONE_MAPPED	Ein Sicherheitsbezeichner (SID) im Eingabesicherheitsdeskriptor konnte in einem Kontosuchevorgang nicht gefunden werden.
ERROR_INVALID_ACL	Die Zugriffssteuerungsliste (ACL) ist ungültig. Dieser Fehler wird zurückgegeben, wenn das SE_DACL_PRESENT Flag im Eingabesicherheitsdeskriptor festgelegt ist und die DACL NULL-ist.

Bemerkungen

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

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

Anmerkung

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
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	sddl.h
Library	Advapi32.lib
DLL-	Advapi32.dll