IDSSAccessControlList Interface Reference

Detailed Description

IDSSAccessControlList is a second-class collection of Access Control Entry objects (ACEs).

Public Member Functions

HRESULT _NewEnum ([out, retval] IUnknown ppNewEnum)

The standard property to return (Visual Basic) enumerator interface.

HRESULT Add ([in, defaultvalue(DssAccessEntryTypeObject)] EnumDSSAccessEntryType ACEType,[out, retval] IDSSAccessControlEntry ppACE)

Add a new access control entry to this list.

HRESULT Clear ()

Clear the contents of this list (removing all entries).

HRESULT Compress ()

Compress the list.

HRESULT ComputeUserRights ([in] IDSSUser *pUser,[out] EnumDSSAccessRightType *pRights)

Compute the rights granted to a specific user.

HRESULT Count ([out, retval] Int32 *pCount)

Return the number of entries in this list.

HRESULT Item ([in] Int32 Index,[out, retval] IDSSAccessControlEntry ppACE)

Get a specific entry in the list.

HRESULT PropagateACL ([in, optional, defaultvalue(DssPropagateACLReserved)] EnumDSSPropagateACL Flags)

Propagate the ACL of a folder to its descents.

HRESULT Remove ([in] VARIANT *pIndex)

Remove a specific entry in the list.

Member Function Documentation

HRESULT IDSSAccessControlList::_NewEnum ( [out, retval] IUnknown ppNewEnum )

The standard property to return (Visual Basic) enumerator interface.
This is the standard property used to return the objects in a collection. This property returns an enumerator object. Calling methods on the enumerator object retrieves the contents of the collection.
Access Required: No additional access is required to access this property. To reach this method, the caller must have passed previous access checks.

Parameters:

ppNewEnum An IUnknown pointer to the enumerator object. The object is actually returned using the standard IEnumVARIANT interface.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSAccessControlList::Add ( [in, defaultvalue(DssAccessEntryTypeObject)] EnumDSSAccessEntryType ACEType,

[out, retval] IDSSAccessControlEntry ppACE

)

Add a new access control entry to this list.
This method adds a new entry to the access control list. The type of the entry must be specified as the only required input parameter. The EnumDSSAccessEntryType enumeration defines the list of access control entries as:

DssAccessEntryTypeReserved Invalid type specification.

DssAccessEntryTypeObject An entry which defines access to an object. This is the default value associated with this method.

DssAccessEntryTypeAudit An entry that defines an entry in the audit trail. Currently, audit trails are not yet implemented.

Access Required: The caller must be granted Control permission on the object to be able to add new entries.

Parameters:

ACEType The type of the access control entry to create.

ppACE An interface to the newly created access control entry.

Returns:
Usual COM result code:

S_OK The caller successfully created a new access control entry.

SEC_E_ACCESS_DENIED The caller was not granted sufficient access to modify the access control list.

HRESULT IDSSAccessControlList::Clear ( )

Clear the contents of this list (removing all entries).
Clear the contents of the list. An empty access control list (implicitly) grants Control access to the current owner.
Access Required: The caller must be granted Control permission on the object to be able to clear the contents of the list.

Returns:
Usual COM result code:

S_OK The caller successfully cleared the contents of the access control list.

SEC_E_ACCESS_DENIED The caller was not granted sufficient access to modify the access control list.

HRESULT IDSSAccessControlList::Compress ( )

Compress the list.
Compress the list by removing the redundant ACEs and combining like ones. The like ones are defined as follows: They have the same ACE type, inheritable, deny/granted, and Trustee. If the like ones are found, they are compressed into one ACE with union of their rights.
Access Required: The caller must be granted Control permission on the object to be able to compress the list.

Returns:
Usual COM result code:

S_OK The caller successfully removed the selected entry from the list.

SEC_E_ACCESS_DENIED The caller was not granted sufficient access to modify the access control list.

HRESULT IDSSAccessControlList::ComputeUserRights ( [in] IDSSUser * pUser,

[out] EnumDSSAccessRightType * pRights

)

Compute the rights granted to a specific user.
This method is used to compute the resolved access rights granted to a specific user for this object. It is intended primarily as a method to assist in the development of an Access Control List editor. This method inspects each non-inheritable entry in the access control list that is marked with type, DssAccessEntryTypeObject. For each entry that applies to the supplied user, the resolved access rights are computed and returned to the caller.
This is not a system-function, but a method to aid the development of access control lists. The user who is logged on may possess other privileges that affect the actual access rights granted to the user.

Access Required: No additional access is required to call this method.

Parameters:

pUser Refers to a user object to analyze access for.

pRights The resolved access rights for this user.

Returns:
Usual COM result code:

S_OK The operation succeeded.

SEC_E_NOT_USER_OBJECT The caller did not supply a User object.

HRESULT IDSSAccessControlList::Count ( [out, retval] Int32 * pCount )

Return the number of entries in this list.
Returns the number of entries in the access control list.
Access Required: No additional access is required to call this method.

Parameters:

pCount The total number of entries in the list.

Returns:
Usual COM result code:

S_OK

HRESULT IDSSAccessControlList::Item ( [in] Int32 Index,

[out, retval] IDSSAccessControlEntry ppACE

)

Get a specific entry in the list.
Return the Nth entry in the access control list.
Access Required: No additional access is required to call this method.

Parameters:

Index The index of the entry to select. Valid values range from 1 to the value of Count.

ppACE The IDSSAccessControlEntry interface of the selected entry.

Returns:
Usual COM result code:

S_OK The caller successfully retrieved the Nth item of the list.

DSSCOM_E_INDEX_OUT_OF_RANGE The caller specified a numeric index that is out of the range of values in this list.

HRESULT IDSSAccessControlList::PropagateACL ( [in, optional, defaultvalue(DssPropagateACLReserved)] EnumDSSPropagateACL Flags )

Propagate the ACL of a folder to its descents.

If the object is not a folder object, no action is performed.

All the ACEs of the propagated ACL are added to the ACLs of the sub-folders. When the propagated ACEs are added into the ACLS of non-folder objects, the inheritable ACEs are added as non-inheritable ACEs.

By default, all the ACEs in this ACL are added to the ACLs of those descents that the caller granted Control permission. All changes are saved.

If DssPropagateACLDirectChildren is set in Flags, ACL is only propagated to the direct children of this folder object.

If DssPropagateACLTemporary is set in Flags, changes are temporary and are not saved.

If DssPropagateACLReplace is set in Flags, ACL on children will be replaced by ACL on the folder object.

Access Required: The caller must be granted Control permission on the object to be able to propagate this ACL to its descents.

Parameters:

Flags It is a bit-wise enumeration value that controls the propagation action. Currently, its available enumeration values are:

DssPropagateACLDirectChildren Propagate ACL only to the direct children of the folder.

DssPropagateACLTemporary Changes are not saved.

DssPropagateACLReplace Replace children's ACL.

Returns:
Usual COM result code:

S_OK The caller successfully removed the selected entry from the list.

SEC_E_ACCESS_DENIED The caller was not granted sufficient access to modify the access control list.

HRESULT IDSSAccessControlList::Remove ( [in] VARIANT * pIndex )

Remove a specific entry in the list.
Remove the Nth entry from the list.
Access Required: The caller must be granted Control permission on the object to be able to remove an entry from the list.

Parameters:

pIndex The index of the entry to select. If pIndex refers to a Long, then valid values range from 1 to the value of Count. If pIndex refers to a (COM interface) pointer, then it must refer to an entry in the list.

Returns:
Usual COM result code:

S_OK The caller successfully removed the selected entry from the list.

SEC_E_ACCESS_DENIED The caller was not granted sufficient access to modify the access control list.

DSSCOM_E_KEY_NOT_FOUND The caller tried to specify an index specification using a string, but there is no way to look up an entry by string.

DSSCOM_E_INDEX_OUT_OF_RANGE The caller specified a numeric index that is out of the range of values in this list.


Public Member Functions
HRESULT	_NewEnum ([out, retval] IUnknown ppNewEnum)
	The standard property to return (Visual Basic) enumerator interface.
HRESULT	Add ([in, defaultvalue(DssAccessEntryTypeObject)] EnumDSSAccessEntryType ACEType,[out, retval] IDSSAccessControlEntry ppACE)
	Add a new access control entry to this list.
HRESULT	Clear ()
	Clear the contents of this list (removing all entries).
HRESULT	Compress ()
	Compress the list.
HRESULT	ComputeUserRights ([in] IDSSUser pUser,[out] EnumDSSAccessRightType pRights)
	Compute the rights granted to a specific user.
HRESULT	Count ([out, retval] Int32 *pCount)
	Return the number of entries in this list.
HRESULT	Item ([in] Int32 Index,[out, retval] IDSSAccessControlEntry ppACE)
	Get a specific entry in the list.
HRESULT	PropagateACL ([in, optional, defaultvalue(DssPropagateACLReserved)] EnumDSSPropagateACL Flags)
	Propagate the ACL of a folder to its descents.
HRESULT	Remove ([in] VARIANT *pIndex)
	Remove a specific entry in the list.