AddAccessDeniedObjectAce

[This is preliminary documentation and subject to change.]

The AddAccessDeniedObjectAce function adds an access-denied ACE to the end of a DACL. The new ACE can deny access to an object, or to a property set or property on an object. You can also use AddAccessDeniedObjectAce to add an ACE that only a specified type of child object can inherit.

BOOL AddAccessDeniedObjectAce(
  PACL pAcl,             // pointer to an ACL
  DWORD dwAceRevision,   // ACL revision level
  DWORD AceFlags,        // ACE inheritance flags
  DWORD AccessMask,      // access mask for the new ACE
  GUID *ObjectTypeGuid,  // type of object protected by the ACE
  GUID *InheritedObjectTypeGuid,  
                         // type of object that can inherit the ACE
  PSID pSid              // SID of the trustee for the new ACE
);
 

Parameters

pAcl

Pointer to a DACL. The AddAccessDeniedObjectAce function adds an access-denied ACE to the end of this DACL. The ACE is in the form of an ACCESS_DENIED_OBJECT_ACE structure.

dwAceRevision

Specifies the revision level of the DACL being modified. This value must be ACL_REVISION_DS. If the DACL's revision level is lower than ACL_REVISION_DS, the function changes it to ACL_REVISION_DS.

AceFlags

A set of bit flags that control ACE inheritance. The function sets these flags in the AceFlags member of the ACE_HEADER structure of the new ACE. This parameter can be a combination of the following values.

Value	Meaning
CONTAINER_INHERIT_ACE
	The ACE is inherited by container objects.
INHERIT_ONLY_ACE
	The ACE does not apply to the object to which the ACL is assigned, but it can be inherited by child objects.
INHERITED_ACE
	Indicates an inherited ACE. This flag allows operations that change the security on a tree of objects to modify inherited ACEs, while not changing ACEs that were directly applied to the object.
NO_PROPAGATE_INHERIT_ACE
	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
	The ACE is inherited by noncontainer objects.

AccessMask

A set of bit flags that use the ACCESS_MASK format to specify the access rights that the new ACE denies to the specified SID. This mask must use the Windows NT access mask format, not the provider-independent access-mask format.

ObjectTypeGuid

Pointer to a GUID structure that identifies the type of object, property set, or property protected by the new ACE. If this parameter is NULL, the new ACE protects the object to which the ACL is assigned.

InheritedObjectTypeGuid

Pointer to a GUID structure that identifies the type of object that can inherit the new ACE. If this parameter is non-NULL, only the specified object type can inherit the ACE. If NULL, any type of child object can inherit the ACE. In either case, inheritance is also controlled by the value of the AceFlags parameter, as well as by any protection against inheritance placed on the child objects.

pSid

Pointer to a SID structure that identifies the user, group, or logon session to which the new ACE grants access.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. If the AceFlags parameter specifies invalid flags, GetLastError returns ERROR_INVALID_FLAGS.

Remarks

If both ObjectTypeGuid and InheritedObjectTypeGuid are NULL, use the AddAccessDeniedAceEx function rather than AddAccessDeniedObjectAce. This is suggested because an ACCESS_DENIED_ACE is smaller and more efficient than an ACCESS_DENIED_OBJECT_ACE.

Although the AddAccessDeniedObjectAce function adds the new ACE to the end of the ACL, access-denied ACEs should appear at the beginning of an ACL. The caller must ensure that ACEs are added to the DACL in the correct order. For more information, see Order of ACEs in a DACL.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

Low-Level Access-Control Overview, Low-Level Access Control Functions, ACCESS_DENIED_ACE, ACCESS_DENIED_OBJECT_ACE, ACE_HEADER, ACL, AddAccessAllowedObjectAce, AddAccessDeniedAceEx, AddAuditAccessObjectAce