Funzione BuildSecurityDescriptorW (aclapi.h)

Articolo
02/23/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 auto-relativo. Il formato auto-relativo rende il descrittore di sicurezza adatto per l'archiviazione in un flusso.

Sintassi

DWORD BuildSecurityDescriptorW(
  [in, optional] PTRUSTEE_W           pOwner,
  [in, optional] PTRUSTEE_W           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_W   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 per il nuovo descrittore di sicurezza. Se la struttura usa il modulo 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 del descrittore di sicurezza originale a cui punta pOldSD. Se pOldSD è NULL o se il SID proprietario in pOldSD è NULL, il SID proprietario è 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 utilizza il modulo 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 è NULL o se il SID del gruppo in pOldSD è NULL, il SID del gruppo è 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 l'elenco DACL in pOldSD, se presente. Se pOldSD è NULL o se il 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 è NULL o se il 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 di 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 è NULL o 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 è NULL o sacl in pOldSD è NULL, il nuovo sacl è NULL.

[in, optional] pOldSD

Puntatore a una struttura di SECURITY_DESCRIPTOR auto-relativa 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 specificate 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.

Commenti

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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	aclapi.h
Libreria	Advapi32.lib
DLL	Advapi32.dll