Função BuildSecurityDescriptorW (aclapi.h)
A função BuildSecurityDescriptor aloca e inicializa um novo descritor de segurança. Essa função pode inicializar o novo descritor de segurança mesclando informações de segurança especificadas com as informações em um descritor de segurança existente. Se você não especificar um descritor de segurança existente, a função inicializará um novo descritor de segurança com base nas informações de segurança especificadas.
A função BuildSecurityDescriptor cria um descritor de segurança auto-relativo. O formato auto-relativo torna o descritor de segurança adequado para armazenar em um fluxo.
Sintaxe
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
);
Parâmetros
[in, optional] pOwner
Um ponteiro para uma estrutura TRUSTEE que identifica o proprietário do novo descritor de segurança. Se a estrutura usar o formulário TRUSTEE_IS_NAME, BuildSecurityDescriptor procurará o SID ( identificador de segurança ) associado ao nome do objeto de confiança especificado.
Se esse parâmetro for NULL, a função usará o SID do proprietário do descritor de segurança original apontado por pOldSD. Se pOldSD for NULL ou se o SID do proprietário em pOldSD for NULL, o SID do proprietário será NULL no novo descritor de segurança.
[in, optional] pGroup
Um ponteiro para uma estrutura TRUSTEE que identifica o SID do grupo primário para o novo descritor de segurança. Se a estrutura usar o formulário TRUSTEE_IS_NAME, BuildSecurityDescriptor procurará o SID associado ao nome de administrador especificado.
Se esse parâmetro for NULL, a função usará o SID do grupo do descritor de segurança original apontado por pOldSD. Se pOldSD for NULL ou se o SID do grupo em pOldSD for NULL, o SID do grupo será NULL no novo descritor de segurança.
[in] cCountOfAccessEntries
O número de estruturas EXPLICIT_ACCESS na matriz pListOfAccessEntries .
[in, optional] pListOfAccessEntries
Um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem informações de controle de acesso para a DACL ( lista de controle de acesso discricionário ) do novo descritor de segurança. A função cria a nova DACL mesclando as informações na matriz com a DACL em pOldSD, se houver. Se pOldSD for NULL ou se a DACL em pOldSD for NULL, a função criará uma nova DACL com base apenas nas informações na matriz. Para obter uma descrição das regras para criar uma ACL de uma matriz de estruturas EXPLICIT_ACCESS , consulte a função SetEntriesInAcl .
Se pListOfAccessEntries for NULL, o novo descritor de segurança obterá a DACL de pOldSD. Nesse caso, se pOldSD for NULL ou se a DACL em pOldSD for NULL, a nova DACL será NULL.
[in] cCountOfAuditEntries
O número de estruturas EXPLICIT_ACCESS na matriz pListOfAuditEntries .
[in, optional] pListOfAuditEntries
Um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem informações de controle de auditoria para a SACL do novo descritor de segurança. A função cria a nova SACL mesclando as informações na matriz com a SACL em pOldSD, se houver. Se pOldSD for NULL ou a SACL em pOldSD for NULL, a função criará uma nova SACL com base apenas nas informações na matriz.
Se pListOfAuditEntries for NULL, o novo descritor de segurança obterá a SACL de pOldSD. Nesse caso, se pOldSD for NULL ou a SACL em pOldSD for NULL, a nova SACL será NULL.
[in, optional] pOldSD
Um ponteiro para uma estrutura de SECURITY_DESCRIPTOR auto-relativa existente e suas informações de segurança associadas. A função cria o novo descritor de segurança mesclando o proprietário, o grupo, o controle de acesso e as informações de controle de auditoria especificados com as informações neste descritor de segurança. Este parâmetro pode ser NULL.
[out] pSizeNewSD
Um ponteiro para uma variável que recebe o tamanho, em bytes, do descritor de segurança.
[out] pNewSD
Um ponteiro para uma variável que recebe um ponteiro para o novo descritor de segurança. A função aloca memória para o novo descritor de segurança. Você deve chamar a função LocalFree para liberar o buffer retornado.
Retornar valor
Se a função for bem-sucedida, a função retornará ERROR_SUCCESS.
Se a função falhar, ela retornará um código de erro diferente de zero definido em WinError.h.
Comentários
A função BuildSecurityDescriptor destina-se a servidores confiáveis que implementam ou expõem a segurança em seus próprios objetos. A função usa descritores de segurança auto-relativos adequados para serialização em um fluxo e armazenamento em disco, como um servidor confiável pode exigir.
Observação
O cabeçalho aclapi.h define BuildSecurityDescriptor como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
Plataforma de Destino | Windows |
Cabeçalho | aclapi.h |
Biblioteca | Advapi32.lib |
DLL | Advapi32.dll |
Confira também
Funções de Controle de Acesso cliente/servidor