Using MAPI with Directory Objects

The Microsoft Exchange Server address book provider provides access to directory objects through the MAPI address book interface. Using MAPI, you can create and delete directory objects, as well as view and change their attributes.

The main requirement for manipulating directory objects through the Microsoft Exchange Server address book provider is that MAPI entry identifiers be generated for the objects. An entry identifier can be created from the object's distinguished name, using the HrCreateDirEntryIDEx function.

    To use MAPI to modify existing directory objects

1. Find the object entry identifier in the directory. The object's presence in the address book means that it is exposed as an addressable entity, such as a mailbox, custom recipient, or distribution list. It is possible to create an entry identifier for an object by using its distinguished name. This provides a more direct way of accessing objects in the directory, including those not exposed in the MAPI address book. For more information about locating an object, see Opening an Object in the Directory and the MAPI Programmer's Reference.
2. Use the object's entry identifier to invoke the IAddrBook::OpenEntry method on the object. This call returns the appropriate interface for performing operations on that object type. For example, if the object type is Mail-Recipient, OpenEntry returns a pointer to the IMailUser interface. With this call, you specify the type of access you want to the object: read/write or read-only.
3. Use methods of the returned interface to read or write the object's attributes, depending on your task. For example, you can call IMAPIProp::SetProps (with the proper parameters, such as PR_COMMENT) on the object to change one or more of its attributes.
4. Repeat step 3 on any other properties, using the appropriate read/write commands, until you've completed your directory work.
5. Use the IMAPIProp::SaveChanges method to save your changes and either keep the object open to perform further operations or close the object. To keep the object open, use the KEEP_OPEN_READ_{ONLY|WRITE} flag in the SaveChanges call.

If your program modifies several objects, its code may look like this:

OpenEntry (object 1)
SetProps(property list) 
GetProps(property list)
SaveChanges( )
Release()
OpenEntry (object 2)
 

To read or write several object properties at once, it is best to perform the task with a single IMAPIProp::SetProps or IMAPIProp::GetProps call. This is more efficient than repeatedly calling these methods and specifying a single property to read or write in each call.

Through the Microsoft Exchange Server address book provider, you can access directory objects that correspond to the five MAPI display types. The following table lists these display types, along with the most commonly used MAPI interface.

Corresponding Directory Objects and MAPI Display Types

The IMailUser interface inherits methods from the IMAPIProp interface. Use the methods of these interfaces to access directory objects and their attributes. An object-valued attribute, which is an attribute whose type is PT_OBJECT, is seen by MAPI as a table. The attribute's values are members of the table. To access these values, use the IMAPITable interface, which is obtained by calling IMAPIProp::OpenProperty on the property of interest.

As with directory access import commands, the directory automatically updates the object's USN after it is modified using MAPI commands. Using MAPI commands in the directory has no effect on the information store. For more information about USNs, see Exporting Objects and Using Directory Access Functions.