| Platform SDK: Exchange Server |
The ACLObject class defines an object that can be used to manipulate the access control entries (ACEs) on a CDO 1.21 (MAPI) folder object.
Instances of the ACLObject COM class can be used to modify or examine the access control entries on a MAPI folder. It has two properties accessible through the exposed IACLObject interface, IACLObject::CDOItemand IACLObject::ACEs. The CDOItem property is write-only and is used to bind the desired CDO 1.21 folder object (and hence the MAPI folder) to the ACLObject object. Once a folder is bound, the ACLObject object internally creates and populates an instance of the ACEs COM class, which is a collection of ACE objects, each containing an access control entry for the folder. You can use the ACEs object to manipulate the collection by adding new objects and deleting or modifying existing objects. To commit changes to the store, call the IACLObject::Updatemethod. The ACE objects are stored in the collection as a list and as a dictionary of entries, where the key is the long-term entry identifier for the member, and the value is the ACE object. The ACE objects can therefore be retrieved from the collection using a valid index or an entry identifier key.
The ACLObject uses the MAPI32 component (MAPI) to communicate with the Exchange Store. If the process or thread that will create the ACLObject is not running with administrative privileges, a MAPI session must first be established before creating an instance of the ACLObject.
Long Term versus Short Term Entry IDs When retrieving a member's entry identifier from the address book, the value returned by the CDO.Recipient (or CDO.AddressEntry) object is the member's short-term entry identifier. When you create an ACE object and set its IACE::IDproperty to the short-term entry identifier, and then subsequently add the object to the ACEs collection, the ACE object's ID property gets internally converted to the long-term entry identifier and the ACE object is then placed in the collection using this long-term entry identifier string as the key. If you plan to use the identifier to access the ACE object in the collection, retrieve the long-term entry identifier from the newly added ACE object's IACE::ID property after adding it to the collection.
The following example in Visual Basic, Scripting Edition (VBScript) demonstrates how to add a new access control entry to a folder.
set session = createobject("MAPI.Session")
' create profile on the fly
session.logon "","",false,true,true,true,"server" & vbLf & "alias"
' get a folder here
set store = session.infostores.item("Public Folders")
set root = session.getFolder(store.fields(&h66310102),store.id).Folders
set fldr = root.item("My Folder")
' get the aclsobject for the folder
set acls = createobject("MSExchange.aclobject")
set acls.cdoitem = fldr ' set the CDO folder to CDOItem
set fldr_aces = acls.aces ' get ACEs for folder
' create a new ace and add member
set newace = createobject("MSExchange.ACE")
' fetch the GAL
set gal = session.addresslists.item(1)
set member = gal.addressentries.item("member_name")
newace.ID = member.id
newace.rights = &H0400 ' role none
fldr_aces.add newace ' add the ACE to the collection
' Internally the newace.id has been
' converted to the long term value.
' newace.id is now different than
' member.id above
fldr_aces.delete newace.id ' then delete it
' note the use of the id property
' the ID is the long-term entry id
acls.update ' commit changes to store
Example Note About Identifiers Notice the use of the ID property when deleting the ACE object from the collection in the previous example. If we had stored the ID for the new ACE object in a string variable, added the object to the collection, and then subsequently used the previously saved ID as an argument to the Delete method, an exception would have been thrown because the identifier would not have been a valid key in the collection. The identifier is internally converted to the long-term entry identifier for the member and used as the key when the ACE object is added to the collection.
For instance,
strId = member.id 'short-term
newace.ID = member.id ' short-term
aces.add newace ' ID gets converted by ACLOBject to long-term id
' and is now stored under this new value.
aces.delete strId ' This would fail. The
' value isn't used to store the ACE object
This would not delete the ACE object from the collection because the ID used would be the short-term entry identifier, not the long-term identifier used to index the object in the dictionary.