Função AccessCheckByTypeAndAuditAlarmW (securitybaseapi.h)

A função AccessCheckByTypeAndAuditAlarm determina se um descritor de segurança concede um conjunto especificado de direitos de acesso ao cliente que está sendo representado pelo thread de chamada. A função pode marcar o acesso do cliente a uma hierarquia de objetos, como um objeto, seus conjuntos de propriedades e propriedades. A função concede ou nega acesso à hierarquia como um todo. Se o descritor de segurança tiver uma SACL ( lista de controle de acesso do sistema ) com ACEs (entradas de controle de acesso ) que se aplicam ao cliente, a função gerará todas as mensagens de auditoria necessárias no log de eventos de segurança.

No momento, não há suporte para alarmes.

Sintaxe

BOOL AccessCheckByTypeAndAuditAlarmW(
  [in]                LPCWSTR              SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                LPCWSTR              ObjectTypeName,
  [in, optional]      LPCWSTR              ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus,
  [out]               LPBOOL               pfGenerateOnClose
);

Parâmetros

[in] SubsystemName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do subsistema que chama a função. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.

[in] HandleId

Um ponteiro para um valor exclusivo que representa o identificador do cliente para o objeto . Se o acesso for negado, o sistema ignorará esse valor.

[in] ObjectTypeName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o tipo de objeto que está sendo criado ou acessado. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.

[in, optional] ObjectName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto que está sendo criado ou acessado. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.

[in] SecurityDescriptor

Um ponteiro para uma estrutura de SECURITY_DESCRIPTOR na qual o acesso é verificado.

[in, optional] PrincipalSelfSid

Um ponteiro para um SID ( identificador de segurança ). Se o descritor de segurança estiver associado a um objeto que representa uma entidade de segurança (por exemplo, um objeto de usuário), o parâmetro PrincipalSelfSid deverá ser o SID do objeto. Ao avaliar o acesso, esse SID substitui logicamente o SID em qualquer ACE que contenha o SID de PRINCIPAL_SELF conhecido (S-1-5-10). Para obter informações sobre SIDs conhecidos, consulte SIDs conhecidos.

Se o objeto protegido não representar uma entidade de segurança, defina esse parâmetro como NULL.

[in] DesiredAccess

Uma máscara de acesso que especifica os direitos de acesso a marcar. Essa máscara deve ter sido mapeada pela função MapGenericMask para não conter direitos de acesso genéricos.

Se esse parâmetro for MAXIMUM_ALLOWED, a função definirá a máscara de acesso GrantedAccess para indicar os direitos máximos de acesso que o descritor de segurança permite ao cliente.

[in] AuditType

O tipo de auditoria a ser gerado. Esse pode ser um dos valores do tipo de enumeração AUDIT_EVENT_TYPE .

[in] Flags

Um sinalizador que controla o comportamento da função se o processo de chamada não tiver o privilégio de SE_AUDIT_NAME habilitado. Se o sinalizador AUDIT_ALLOW_NO_PRIVILEGE estiver definido, a função executará o marcar de acesso sem gerar mensagens de auditoria quando o privilégio não estiver habilitado. Se esse parâmetro for zero, a função falhará se o privilégio não estiver habilitado.

[in, out, optional] ObjectTypeList

Um ponteiro para uma matriz de estruturas OBJECT_TYPE_LIST que identificam a hierarquia de tipos de objeto para os quais marcar acesso. Cada elemento na matriz especifica um GUID que identifica o tipo de objeto e um valor que indica o nível do tipo de objeto na hierarquia de tipos de objeto. A matriz não deve ter dois elementos com o mesmo GUID.

A matriz deve ter pelo menos um elemento. O primeiro elemento na matriz deve estar no nível zero e identificar o próprio objeto. A matriz pode ter apenas um elemento de nível zero. O segundo elemento é um subobjeto, como um conjunto de propriedades, no nível 1. Seguindo cada entrada de nível 1 estão as entradas subordinadas para os subobjetos de nível 2 a 4. Portanto, os níveis para os elementos na matriz podem ser {0, 1, 2, 2, 1, 2, 3}. Se a lista de tipos de objeto estiver fora de ordem, AccessCheckByTypeAndAuditAlarm falhará e GetLastError retornará ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

O número de elementos na matriz ObjectTypeList .

[in] GenericMapping

Um ponteiro para a estrutura GENERIC_MAPPING associada ao objeto para o qual o acesso está sendo verificado.

[in] ObjectCreation

Um sinalizador que determina se o aplicativo de chamada criará um novo objeto quando o acesso for concedido. Um valor true indica que o aplicativo criará um novo objeto. Um valor false indica que o aplicativo abrirá um objeto existente.

[out] GrantedAccess

Um ponteiro para uma máscara de acesso que recebe os direitos de acesso concedidos. Se AccessStatus estiver definido como FALSE, a função definirá a máscara de acesso como zero. Se a função falhar, ela não definirá a máscara de acesso.

[out] AccessStatus

Um ponteiro para uma variável que recebe os resultados da marcar de acesso. Se o descritor de segurança permitir os direitos de acesso solicitados ao cliente, AccessStatus será definido como TRUE. Caso contrário, AccessStatus será definido como FALSE e você poderá chamar GetLastError para obter informações de erro estendidas.

[out] pfGenerateOnClose

Um ponteiro para um sinalizador definido pela rotina de geração de auditoria quando a função retorna. Passe esse sinalizador para a função ObjectCloseAuditAlarm quando o identificador do objeto for fechado.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Para obter mais informações, consulte a Visão geral de como o AccessCheck funciona .

Se os parâmetros PrincipalSelfSid e ObjectTypeList forem NULL, o parâmetro AuditType será AuditEventObjectAccess e o parâmetro Flags for zero, AccessCheckByTypeAndAuditAlarm será executado da mesma forma que a função AccessCheckAndAuditAlarm .

A matriz ObjectTypeList não representa necessariamente todo o objeto definido. Em vez disso, ele representa esse subconjunto do objeto para o qual marcar acesso. Por exemplo, para marcar acesso a duas propriedades em um conjunto de propriedades, especifique uma lista de tipos de objeto com quatro elementos: o próprio objeto no nível zero, a propriedade definida no nível 1 e as duas propriedades no nível 2.

A função AccessCheckByTypeAndAuditAlarm avalia ACEs que se aplicam ao próprio objeto e ACEs específicos do objeto para os tipos de objeto listados na matriz ObjectTypeList . A função ignora ACEs específicas do objeto para tipos de objeto não listados na matriz ObjectTypeList . Assim, os resultados retornados no parâmetro AccessStatus indicam o acesso permitido ao subconjunto do objeto definido pelo parâmetro ObjectTypeList , não ao objeto inteiro.

Para obter mais informações sobre como uma hierarquia de ACEs controla o acesso a um objeto e seus subobjetos, consulte ACEs para controlar o acesso às propriedades de um objeto.

Para gerar mensagens de auditoria no log de eventos de segurança, o processo de chamada deve ter o privilégio SE_AUDIT_NAME habilitado. O sistema verifica esse privilégio no token primário do processo de chamada, não no token de representação do thread. Se o parâmetro Flags incluir o sinalizador AUDIT_ALLOW_NO_PRIVILEGE, a função executará o marcar de acesso sem gerar mensagens de auditoria quando o privilégio não estiver habilitado.

A função AccessCheckByTypeAndAuditAlarm falhará se o thread de chamada não estiver representando um cliente.

Se o descritor de segurança não contiver SIDs de proprietário e grupo, AccessCheckByTypeAndAuditAlarm falhará com ERROR_INVALID_SECURITY_DESCR.

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	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll

Confira também

AUDIT_EVENT_TYPE
AccessCheck
AccessCheckAndAuditAlarm
AccessCheckByType
AccessCheckByTypeResultList
AccessCheckByTypeResultListAndAuditAlarm
Controle de Acesso cliente/servidor
Funções de Controle de Acesso cliente/servidor
GENERIC_MAPPING
Como o AccessCheck funciona
MakeAbsoluteSD
MapGenericMask
OBJECT_TYPE_LIST
ObjectCloseAuditAlarm
PRIVILEGE_SET
SECURITY_DESCRIPTOR