LookupSecurityDescriptorPartsA-Funktion (aclapi.h)

Artikel
08/22/2023

Die LookupSecurityDescriptorParts-Funktion ruft Sicherheitsinformationen aus einem selbstrelativen Sicherheitsdeskriptor ab.

Syntax

DWORD LookupSecurityDescriptorPartsA(
  [out, optional] PTRUSTEE_A           *ppOwner,
  [out, optional] PTRUSTEE_A           *ppGroup,
  [out, optional] PULONG               pcCountOfAccessEntries,
  [out, optional] PEXPLICIT_ACCESS_A   *ppListOfAccessEntries,
  [out, optional] PULONG               pcCountOfAuditEntries,
  [out, optional] PEXPLICIT_ACCESS_A   *ppListOfAuditEntries,
  [in]            PSECURITY_DESCRIPTOR pSD
);

Parameter

[out, optional] ppOwner

Ein Zeiger auf eine Variable, die einen Zeiger auf eine TRUSTEE-Struktur empfängt. Die Funktion sucht den Namen, der dem Besitzersicherheitsbezeichner (SID) im pSD-Sicherheitsdeskriptor zugeordnet ist, und gibt einen Zeiger auf den Namen im ptstrName-Member der TRUSTEE-Struktur zurück. Die Funktion legt den TrusteeForm-Member auf TRUSTEE_IS_NAME fest.

Dieser Parameter kann NULL sein, wenn Sie nicht an dem Namen des Besitzers interessiert sind.

[out, optional] ppGroup

Ein Zeiger auf eine Variable, die einen Zeiger auf eine TRUSTEE-Struktur empfängt. Die Funktion sucht den Namen, der der primären Gruppen-SID des Sicherheitsdeskriptors zugeordnet ist, und gibt einen Zeiger auf den Namen im ptstrName-Member der TRUSTEE-Struktur zurück. Die Funktion legt den TrusteeForm-Member auf TRUSTEE_IS_NAME fest.

Dieser Parameter kann NULL sein, wenn Sie nicht an dem Namen der Gruppe interessiert sind.

[out, optional] pcCountOfAccessEntries

Ein Zeiger auf eine ULONG , die die Anzahl der EXPLICIT_ACCESS-Strukturen empfängt, die im pListOfAccessEntries-Array zurückgegeben werden. Dieser Parameter kann nur NULL sein, wenn der pListOfAccessEntries-Parameter ebenfalls NULL ist.

[out, optional] ppListOfAccessEntries

Ein Zeiger auf eine Variable, die einen Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen empfängt, die die Zugriffssteuerungseinträge (Access Control Entries , ACEs) in der diskretionären Zugriffssteuerungsliste (DACL) des Sicherheitsdeskriptors beschreiben. Die TRUSTEE-Struktur in diesen EXPLICIT_ACCESS-Strukturen verwendet das TRUSTEE_IS_NAME Formular. Eine Beschreibung, wie ein Array von EXPLICIT_ACCESS Strukturen die ACEs in einer Zugriffssteuerungsliste (Access Control List , ACL) beschreibt, finden Sie in der GetExplicitEntriesFromAcl-Funktion . Wenn dieser Parameter NULL ist, muss der cCountOfAccessEntries-Parameter ebenfalls NULL sein.

[out, optional] pcCountOfAuditEntries

Ein Zeiger auf eine ULONG , die die Anzahl der EXPLICIT_ACCESS Strukturen empfängt, die im pListOfAuditEntries-Array zurückgegeben werden. Dieser Parameter kann nur NULL sein, wenn der pListOfAuditEntries-Parameter ebenfalls NULL ist.

[out, optional] ppListOfAuditEntries

Ein Zeiger auf eine Variable, die einen Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen empfängt, die die ACEs in der Systemzugriffssteuerungsliste (SACL) des Sicherheitsdeskriptors beschreiben. Die TRUSTEE-Struktur in diesen EXPLICIT_ACCESS-Strukturen verwendet das TRUSTEE_IS_NAME-Formular. Wenn dieser Parameter NULL ist, muss der cCountOfAuditEntries-Parameter ebenfalls NULL sein.

[in] pSD

Ein Zeiger auf einen vorhandenen selbstrelativen Sicherheitsdeskriptor , aus dem die Funktion Sicherheitsinformationen abruft.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ERROR_SUCCESS zurück.

Wenn die Funktion fehlschlägt, gibt sie einen nichtzero-Fehlercode zurück, der in WinError.h definiert ist.

Hinweise

Die LookupSecurityDescriptorParts-Funktion ruft die Namen des Besitzers und der primären Gruppe des Sicherheitsdeskriptors ab. Diese Funktion gibt auch Beschreibungen der ACEs in der DACL und Überwachungssteuerungseinträge in der SACL des Sicherheitsdeskriptors zurück.

Die anderen Parameter als pSD können NULL sein, wenn Sie nicht an den Informationen interessiert sind. Wenn Sie keine Informationen zur DACL wünschen, müssen sowohl pListOfAccessEntries als auch cCountOfAuditEntriesNULL sein. Wenn Sie keine Informationen zur SACL wünschen, müssen sowohl pListOfAuditEntries als auch cCountOfAuditEntriesNULL sein. Wenn Sie DACL- oder SACL-Informationen benötigen, dürfen beide entsprechenden Parameter nicht NULL sein.

Wenn Sie mit der Verwendung eines der Puffer abgeschlossen haben, die von den Parametern pOwner, pGroup, pListOfAccessEntries oder pListOfAuditEntries zurückgegeben werden, geben Sie sie frei, indem Sie die Funktion LocalFree aufrufen.

Die LookupSecurityDescriptorParts-Funktion ist für vertrauenswürdige Server vorgesehen, die Sicherheit für ihre eigenen Objekte implementieren oder verfügbar machen. Die Funktion funktioniert mit einem selbstrelativen Sicherheitsdeskriptor, der zum Serialisieren in einen Datenstrom und zum Speichern auf datenträger geeignet ist, wie es ein vertrauenswürdiger Server möglicherweise erfordert.

Hinweis

Der aclapi.h-Header definiert LookupSecurityDescriptorParts als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	aclapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll