BuildSecurityDescriptorA-Funktion (aclapi.h)
Die BuildSecurityDescriptor-Funktion weist einen neuen Sicherheitsdeskriptor zu und initialisiert diesen. Diese Funktion kann den neuen Sicherheitsdeskriptor initialisieren, indem die angegebenen Sicherheitsinformationen mit den Informationen in einem vorhandenen Sicherheitsdeskriptor zusammengeführt werden. Wenn Sie keinen vorhandenen Sicherheitsdeskriptor angeben, initialisiert die Funktion basierend auf den angegebenen Sicherheitsinformationen einen neuen Sicherheitsdeskriptor.
Die BuildSecurityDescriptor-Funktion erstellt einen selbstrelativen Sicherheitsdeskriptor. Durch das selbstrelative Format eignet sich der Sicherheitsdeskriptor zum Speichern in einem Stream.
Syntax
DWORD BuildSecurityDescriptorA(
[in, optional] PTRUSTEE_A pOwner,
[in, optional] PTRUSTEE_A pGroup,
[in] ULONG cCountOfAccessEntries,
[in, optional] PEXPLICIT_ACCESS_A pListOfAccessEntries,
[in] ULONG cCountOfAuditEntries,
[in, optional] PEXPLICIT_ACCESS_A pListOfAuditEntries,
[in, optional] PSECURITY_DESCRIPTOR pOldSD,
[out] PULONG pSizeNewSD,
[out] PSECURITY_DESCRIPTOR *pNewSD
);
Parameter
[in, optional] pOwner
Ein Zeiger auf eine TRUSTEE-Struktur , die den Besitzer für die neue Sicherheitsbeschreibung identifiziert. Wenn die Struktur das formular TRUSTEE_IS_NAME verwendet, sucht BuildSecurityDescriptor nach dem Sicherheitsbezeichner (SID), der dem angegebenen Treuhändernamen zugeordnet ist.
Wenn dieser Parameter NULL ist, verwendet die Funktion die Besitzer-SID aus dem ursprünglichen Sicherheitsdeskriptor, auf den pOldSD verweist. Wenn pOldSDNULL ist oder die Besitzer-SID in pOldSDNULL ist, ist die Besitzer-SID im neuen Sicherheitsdeskriptor NULL.
[in, optional] pGroup
Ein Zeiger auf eine TRUSTEE-Struktur , die die primäre Gruppen-SID für die neue Sicherheitsbeschreibung identifiziert. Wenn die Struktur das formular TRUSTEE_IS_NAME verwendet, sucht BuildSecurityDescriptor nach der SID, die dem angegebenen Trustee-Namen zugeordnet ist.
Wenn dieser Parameter NULL ist, verwendet die Funktion die Gruppen-SID der ursprünglichen Sicherheitsbeschreibung, auf die pOldSD verweist. Wenn pOldSDNULL ist oder die Gruppen-SID in pOldSDNULL ist, ist die Gruppen-SID null in der neuen Sicherheitsbeschreibung.
[in] cCountOfAccessEntries
Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfAccessEntries-Array .
[in, optional] pListOfAccessEntries
Ein Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen, die Zugriffssteuerungsinformationen für die diskretionäre Zugriffssteuerungsliste (DACL) der neuen Sicherheitsbeschreibung beschreiben. Die Funktion erstellt die neue DACL, indem sie die Informationen im Array mit der DACL in pOldSD zusammenführen, falls vorhanden. Wenn pOldSDNULL ist oder die DACL in pOldSDNULL ist, erstellt die Funktion eine neue DACL, die ausschließlich auf den Informationen im Array basiert. Eine Beschreibung der Regeln zum Erstellen einer ACL aus einem Array von EXPLICIT_ACCESS Strukturen finden Sie in der SetEntriesInAcl-Funktion .
Wenn pListOfAccessEntriesNULL ist, ruft der neue Sicherheitsdeskriptor die DACL von pOldSD ab. Wenn pOldSDNULL ist oder die DACL in pOldSDNULL ist, ist die neue DACL NULL.
[in] cCountOfAuditEntries
Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfAuditEntries-Array .
[in, optional] pListOfAuditEntries
Ein Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen, die Überwachungssteuerungsinformationen für die SACL des neuen Sicherheitsdeskriptors beschreiben. Die Funktion erstellt die neue SACL, indem sie die Informationen im Array mit der SACL in pOldSD zusammenführen, falls vorhanden. Wenn pOldSDNULL oder die SACL in pOldSDNULL ist, erstellt die Funktion eine neue SACL, die ausschließlich auf den Informationen im Array basiert.
Wenn pListOfAuditEntriesNULL ist, ruft der neue Sicherheitsdeskriptor die SACL von pOldSD ab. Wenn pOldSDNULL ist oder die SACL in pOldSDNULL ist, ist die neue SACL NULL.
[in, optional] pOldSD
Ein Zeiger auf eine vorhandene selbst relative SECURITY_DESCRIPTOR-Struktur und die zugehörigen Sicherheitsinformationen. Die Funktion erstellt den neuen Sicherheitsdeskriptor, indem sie die angegebenen Besitzer-, Gruppen-, Zugriffssteuerungs- und Überwachungssteuerungsinformationen mit den Informationen in diesem Sicherheitsdeskriptor zusammenführen. Dieser Parameter kann NULL sein.
[out] pSizeNewSD
Ein Zeiger auf eine Variable, die die Größe des Sicherheitsdeskriptors in Bytes empfängt.
[out] pNewSD
Ein Zeiger auf eine Variable, die einen Zeiger auf die neue Sicherheitsbeschreibung empfängt. Die Funktion weist Arbeitsspeicher für die neue Sicherheitsbeschreibung zu. Sie müssen die Funktion LocalFree aufrufen, um den zurückgegebenen Puffer freizugeben.
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 BuildSecurityDescriptor-Funktion ist für vertrauenswürdige Server vorgesehen, die Sicherheit für ihre eigenen Objekte implementieren oder verfügbar machen. Die Funktion verwendet selbstrelative Sicherheitsdeskriptoren, die zum Serialisieren in einen Stream und zum Speichern auf dem Datenträger geeignet sind, wie es ein vertrauenswürdiger Server möglicherweise erfordert.
Hinweis
Der aclapi.h-Header definiert BuildSecurityDescriptor 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 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 |
Weitere Informationen
Client-/Server-Access Control-Funktionen