INFO: WAB: Working with Identities and Folders

In version 5.0 of the Windows Address Book (WAB) application programming interface (API), two new flags, WAB_ENABLE_PROFILES and WAB_PROFILE_CONTENTS, are added to take advantage of the new identities that are used by Outlook Express. This article discusses how to make use of these flags to process the identity and folder information that is available through the WAB API.

Identities

These new flags affect the information that is returned by the WAB API based on the current identity. For additional information on identities and how they are maintained in the registry, click the article number below to view the article in the Microsoft Knowledge Base: The WAB API refers to identities as profiles. This is not to be confused with profiles as used in Extended Messaging Application Programming Interface (MAPI); the two are not related.

For the WAB API, the important key is HKEY_CURRENT_USERS\Identities\Last User ID. You can set this key with the RegSetValueEx function to influence which identity WAB works with.

WAB Flags

The WAB_ENABLE_PROFILES flag is defined in Wabapi.h and is passed in the ulFlags member of the WAB_PARAM parameter in a call to the WABOpen function. This flag signals the WAB to open an identity-aware session.

The WAB_PROFILE_CONTENTS flag is defined in Wabdefs.h and is passed in the ulFlags parameter of the IABContainer::GetContentsTable method. In an identity-aware session, this flag forces the inclusion of all of an identity's contacts in the returned table.

Effect of Setting Last User ID

{00000000-0000-0000-0000-000000000000}

With WAB_ENABLE_PROFILES: The user is prompted to select an identity. This identity is set as the current identity, and is used as described below.Without WAB_ENABLE_PROFILES: All contacts for all identities and all shared contacts will be visible in the address book container that is accessed through the IAddrBook::GetPAB function.

The GUID of a Given Identity

With WAB_ENABLE_PROFILES: The WAB API will only access this identity's contacts.Without WAB_ENABLE_PROFILES: All contacts for all identities and all shared contacts will be visible in the address book container that is accessed through the IAddrBook::GetPAB function.

Folders

The Address Book viewer (Wab.exe) allows users to create subfolders under their main folder. These subfolders are implemented as extra Address Book containers under the Root Container, and will be visible there if WAB_ENABLE_PROFILES is used. Each Address Book container representing a folder will contain the contacts for that folder.

IABContainer and WAB_PROFILE_CONTENTS

If profiles are enabled (WAB_ENABLE_PROFILES), passing WAB_PROFILE_CONTENTS in GetContentsTable for any IABContainer forces the returned contents table to include all contacts available to the current identity. This includes all shared contacts and all contacts contained in all subfolders for the identity.

If profiles are not enabled, passing WAB_PROFILE_CONTENTS has no effect. The "Address Book" container will always contain all contacts and shared contacts for all users.

The Root Container and GetPAB

Typically, you obtain an IABContainer pointer by calling IAddrBook::GetPAB and passing the returned entry ID to IAddrBook::OpenEntry. This returns the primary address book container for the given identity. An alternate method of getting IABContainer pointers is to call IAddrBook::OpenEntry with a NULL entry ID. This will return the Root Container for the address book. The contents table for the Root Container will contain rows for the following address book containers in this order:

• "Address Book", if not using WAB_ENABLE_PROFILES.
• "Somebody's Contacts", if using WAB_ENABLE_PROFILES and "Somebody's" identity.
• Each subfolder for "Somebody", if using WAB_ENABLE_PROFILES and "Somebody"'s identity.
• Each shared subfolder, if using WAB_ENABLE_PROFILES.
• Each Lightweight Directory Access Protocol (LDAP) Directory Service that is currently available.

For additional information, see "WAB and Multi-User/Multi-Identity Profiles " at the following Microsoft Developer Network (MSDN) Web sit: For WAB documentation, see the following article: