Funzione BuildSecurityDescriptorA (aclapi.h)

Articolo
11/20/2024

La funzione BuildSecurityDescriptor alloca e inizializza un nuovo descrittore di sicurezza . Questa funzione può inizializzare il nuovo descrittore di sicurezza unendo le informazioni di sicurezza specificate con le informazioni in un descrittore di sicurezza esistente. Se non si specifica un descrittore di sicurezza esistente, la funzione inizializza un nuovo descrittore di sicurezza in base alle informazioni di sicurezza specificate.

La funzione BuildSecurityDescriptor crea un descrittore di sicurezza self-relative . Il formato auto-relativo rende il descrittore di sicurezza adatto per l'archiviazione in un flusso.

Sintassi

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
);

Parametri

[in, optional] pOwner

Puntatore a una struttura TRUSTEE che identifica il proprietario del nuovo descrittore di sicurezza. Se la struttura usa il modulo di TRUSTEE_IS_NAME, BuildSecurityDescriptor cerca l'identificatore di sicurezza (SID) associato al nome del trustee specificato.

Se questo parametro è NULL, la funzione usa il SID proprietario dal descrittore di sicurezza originale a cui punta pOldSD. Se pOldSD è NULLo se il SID del proprietario in pOldSD è null, il SID del proprietario viene NULL nel nuovo descrittore di sicurezza.

[in, optional] pGroup

Puntatore a una struttura TRUSTEE che identifica il SID del gruppo primario per il nuovo descrittore di sicurezza. Se la struttura usa il form TRUSTEE_IS_NAME, BuildSecurityDescriptor cerca il SID associato al nome del trustee specificato.

Se questo parametro è NULL, la funzione usa il SID del gruppo dal descrittore di sicurezza originale a cui punta pOldSD. Se pOldSD è NULLo se il SID del gruppo in pOldSD è null, il SID del gruppo viene NULL nel nuovo descrittore di sicurezza.

[in] cCountOfAccessEntries

Numero di strutture EXPLICIT_ACCESS nella matrice pListOfAccessEntries.

[in, optional] pListOfAccessEntries

Puntatore a una matrice di strutture EXPLICIT_ACCESS che descrivono le informazioni di controllo di accesso per l'elenco di controllo di accesso discrezionale (DACL) del nuovo descrittore di sicurezza. La funzione crea il nuovo DACL unendo le informazioni nella matrice con il DACL in pOldSD, se presente. Se pOldSD è NULLo se l'elenco DACL in pOldSD è NULL, la funzione crea un nuovo DACL basato esclusivamente sulle informazioni nella matrice. Per una descrizione delle regole per la creazione di un ACL da una matrice di strutture EXPLICIT_ACCESS, vedere la funzione SetEntriesInAcl.

Se pListOfAccessEntries è NULL, il nuovo descrittore di sicurezza ottiene l'elenco DACL da pOldSD. In questo caso, se pOldSD è nullo se l' DACL in pOldSD è null, il nuovo DACL è NULL.

[in] cCountOfAuditEntries

Numero di strutture EXPLICIT_ACCESS nella matrice pListOfAuditEntries.

[in, optional] pListOfAuditEntries

Puntatore a una matrice di strutture EXPLICIT_ACCESS che descrivono le informazioni sul controllo per l'elenco sacl del nuovo descrittore di sicurezza. La funzione crea il nuovo sacl unendo le informazioni nella matrice con SACL in pOldSD, se presente. Se pOldSD è NULLo SACL in pOldSD è NULL, la funzione crea un nuovo sacl basato esclusivamente sulle informazioni nella matrice.

Se pListOfAuditEntries è NULL, il nuovo descrittore di sicurezza ottiene l'oggetto SACL da pOldSD. In questo caso, se pOldSD è NULLo SACL in pOldSD è NULL, il nuovo sacl è NULL.

[in, optional] pOldSD

Puntatore a una struttura di SECURITY_DESCRIPTOR self-relative esistente e alle informazioni di sicurezza associate. La funzione compila il nuovo descrittore di sicurezza unendo il proprietario, il gruppo, il controllo di accesso e le informazioni sul controllo di controllo specificati con le informazioni contenute in questo descrittore di sicurezza. Questo parametro può essere NULL.

[out] pSizeNewSD

Puntatore a una variabile che riceve le dimensioni, in byte, del descrittore di sicurezza.

[out] pNewSD

Puntatore a una variabile che riceve un puntatore al nuovo descrittore di sicurezza. La funzione alloca memoria per il nuovo descrittore di sicurezza. È necessario chiamare la funzione LocalFree per liberare il buffer restituito.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce ERROR_SUCCESS.

Se la funzione ha esito negativo, restituisce un codice di errore diverso da zero definito in WinError.h.

Osservazioni

La funzione BuildSecurityDescriptor è destinata a server attendibili che implementano o espongono la sicurezza nei propri oggetti. La funzione usa descrittori di sicurezza auto-relativi adatti per la serializzazione in un flusso e l'archiviazione su disco, in quanto un server attendibile potrebbe richiedere.

Nota

L'intestazione aclapi.h definisce BuildSecurityDescriptor come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	aclapi.h
libreria	Advapi32.lib
dll	Advapi32.dll