GetFileSecurityA-Funktion (winbase.h)

Artikel
08/27/2023

Die GetFileSecurity-Funktion ruft angegebene Informationen zur Sicherheit einer Datei oder eines Verzeichnisses ab. Die erhaltenen Informationen werden durch die Zugriffsrechte und Berechtigungen des Aufrufers eingeschränkt.

Die GetNamedSecurityInfo-Funktion bietet ähnliche Funktionen wie GetFileSecurity für Dateien sowie für andere Objekttypen.

Syntax

BOOL GetFileSecurityA(
  [in]            LPCSTR               lpFileName,
  [in]            SECURITY_INFORMATION RequestedInformation,
  [out, optional] PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            DWORD                nLength,
  [out]           LPDWORD              lpnLengthNeeded
);

Parameter

[in] lpFileName

Ein Zeiger auf eine NULL-endende Zeichenfolge, die die Datei oder das Verzeichnis angibt, für die Sicherheitsinformationen abgerufen werden.

[in] RequestedInformation

Ein SECURITY_INFORMATION Wert, der die angeforderten Sicherheitsinformationen identifiziert.

[out, optional] pSecurityDescriptor

Ein Zeiger auf einen Puffer, der eine Kopie des Sicherheitsdeskriptors des durch den lpFileName-Parameter angegebenen Objekts empfängt. Der aufrufende Prozess muss über die Berechtigung verfügen, die angegebenen Aspekte der Sicherheits-status des Objekts anzuzeigen. Die SECURITY_DESCRIPTOR-Struktur wird im selbstrelativen Sicherheitsdeskriptorformat zurückgegeben.

[in] nLength

Gibt die Größe des Puffers in Bytes an, auf den der pSecurityDescriptor-Parameter verweist.

[out] lpnLengthNeeded

Ein Zeiger auf die Variable, die die Anzahl der Bytes empfängt, die zum Speichern des vollständigen Sicherheitsdeskriptors erforderlich sind. Wenn die zurückgegebene Anzahl von Bytes kleiner oder gleich nLength ist, wird der gesamte Sicherheitsdeskriptor im Ausgabepuffer zurückgegeben. Andernfalls wird keiner der Deskriptoren zurückgegeben.

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.

Hinweise

Um den Besitzer, die Gruppe oder die DACL aus dem Sicherheitsdeskriptor für die angegebene Datei oder das angegebene Verzeichnis zu lesen, muss die DACL für die Datei oder das Verzeichnis READ_CONTROL Zugriff auf den Aufrufer gewähren, oder der Aufrufer muss der Besitzer der Datei oder des Verzeichnisses sein.

Um die SACL einer Datei oder eines Verzeichnisses zu lesen, muss die berechtigung SE_SECURITY_NAME für den aufrufenden Prozess aktiviert sein.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll