Funzione BuildSecurityDescriptorA (aclapi.h)

Articolo
03/14/2023

La funzione BuildSecurityDescriptor alloca e inizializza un nuovo descrittore di sicurezza. Questa funzione può inizializzare il nuovo descrittore di sicurezza combinando 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 TRUSTEEE che identifica il proprietario del nuovo descrittore di sicurezza. Se la struttura usa il modulo TRUSTEE_IS_NAME, BuildSecurityDescriptor cerca l'identificatore di sicurezza (SID) associato al nome trustee specificato.

Se questo parametro è NULL, la funzione usa il SID proprietario dal descrittore di sicurezza originale a cui fa riferimento 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 TRUSTEEE che identifica il SID del gruppo primario per il nuovo descrittore di sicurezza. Se la struttura usa il modulo TRUSTEE_IS_NAME, BuildSecurityDescriptor cerca il SID associato al nome trustee specificato.

Se questo parametro è NULL, la funzione usa il SID del gruppo dal descrittore di sicurezza originale a cui fa riferimento 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 degli accessi discrezionale del nuovo descrittore di sicurezza. La funzione crea il nuovo daCL combinando le informazioni nella matrice con il 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 il codice 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 sul controllo per il descrittore di sicurezza SACL del nuovo descrittore di sicurezza. La funzione crea il nuovo SACL combinando le informazioni nella matrice con SACL in pOldSD, se presente. Se pOldSD è NULL o SACL in pOldSD è NULL, la funzione crea una nuova SACL basata esclusivamente sulle informazioni nella matrice.

Se pListOfAuditEntries è NULL, il nuovo descrittore di sicurezza ottiene 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 self-relative esistente e alle relative informazioni di sicurezza associate. La funzione compila il nuovo descrittore di sicurezza combinando il proprietario, il gruppo, il controllo di accesso e le informazioni sul controllo di controllo 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 self-relative 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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