3.3 Personal Address Books

Managing personal address books containers and manipulating items within the personal address book containers is different, as shown in the following sections:

3.3.1 Personal Address Book Management

Personal Address Book management event types include the following:

  • AddressBookAdd: Used when a new Personal Address Book is created.

  • AddressBookDelete: Used when an existing Personal Address Book is deleted.

  • AddressBookModify: Used when an existing Personal Address Book is modified.

3.3.2 Personal Address Book Items

Additions, modifications, and deletions to Personal Address Book items can produce more event records than expected. The reason for the extra events is because of the way the Personal Address Book code was written.

First, the Personal Address Book code creates the item. Next, it modifies the item. Thus, two event records are created for each Personal Address Book addition. For example, when adding a contact to a Personal Address Book, two different event records are created. The first record is AddressBookItemAdd. The second event is AddressBookItemModify (because the created item is now modified).

The following sections explain the various events associated with Personal Address Book actions:

Adding Personal Address Book Items

When adding a contact, group, resource, or organization to a Personal Address Book, you might get more events than just AddressBookItemAdd. For example, if you add a resource that specifies an owner that currently does not exist in the Personal Address Book, you receive the following three events:

  • AddressBookItemAdd: Created for the owner that is not in the Personal Address Book.

  • AddressBookItemAdd: Created for the resource itself.

  • AddressBookItemModify: Created for the resource for the owner.

When a contact, group, resource, or organization is added and it references another contact, group, resource, or organization that does not exist in the current PAB, the referenced address book object is created first. This produces an extra AddressBookItemAdd event.

<gwe:getEventsResponse>
   <gwe:events>
      <gwe:event>
         <gwe:event>AddressBookItemAdd</gwe:event>
         <gwe:id>44D0AAA2.domain1.po1.104.16E3837.1.DF.1</gwe:id>
         <gwe:timeStamp>2012-08-02T19:37:38Z</gwe:timeStamp>
         <gwe:container>42C510EA.domain1.po1.104.16E3837.1.3.1@53
                </gwe:container> 
         <gwe:key>GWEvents</gwe:key>
         <gwe:uid>10086</gwe:uid>
         <gwe:type>Contact</gwe:type>
      </gwe:event>
      <gwe:event>
         <gwe:event>AddressBookItemModify</gwe:event>
         <gwe:id>44D0AAA2.domain1.po1.104.16E3837.1.E0.1</gwe:id>
         <gwe:timeStamp>2012-08-02T19:37:39Z</gwe:timeStamp>
         <gwe:field>Owner</gwe:field>
         <gwe:key>GWEvents</gwe:key>
         <gwe:uid>10088</gwe:uid>
         <gwe:type>Resource</gwe:type>
      </gwe:event>
      <gwe:event>
         <gwe:event>AddressBookItemAdd</gwe:event>
         <gwe:id>44D0AAA2.domain1.po1.104.16E3837.1.E0.1</gwe:id>
         <gwe:timeStamp>2012-08-02T19:37:39Z</gwe:timeStamp>
         <gwe:container>42C510EA.domain1.po1.104.16E3837.1.3.1@53
              </gwe:container>
         <gwe:key>GWEvents</gwe:key>
         <gwe:uid>10087</gwe:uid>
         <gwe:type>Resource</gwe:type>
      </gwe:event>
   </gwe:events>
   <gwe:status>
      <gwt:code>0</gwt:code>
   </gwe:status>
</gwe:getEventsResponse>

When creating a Personal Address Book group, you also create an AddressBookItemAdd event for each member of the group. For example, if a group is created with two contacts, the following four events are created:

  • AddressBookItemAdd: Created for the group.

  • AddressBookItemModify: Created for the group modification.

  • AddressBookItemAdd: Created for the first contact in the group.

  • AddressBookItemAdd: Created for the second contact in the group.

Deleting Personal Address Book Items

When you delete a Personal Address Book item, you can expect to receive the following events:

  • AddressBookItemDelete: Created when deleting a contact, organization, or resource.

  • AddressBookItemDelete: Created when deleting a Personal Address Book group itself and when deleting each member of the group.

Modifying Personal Address Book Items

When a Personal Address Book item is modified, an event record is created. By default, the event record does not include a field element because the event record is generic. It tells the listening application that a field on an address book item has changed, but it does not tell the application listener what specific fields have changed.

The following is an example of a generic event record that does not include a field element:

<gwe:event>
   <gwe:event>AddressBookItemModify</gwe:event>
   <gwe:id>438B0F64.domain1.po1.104.16E3837.1.90.1</gwe:id>
   <gwe:timeStamp>2012-11-28T21:25:39Z</gwe:timeStamp>
   <gwe:container>434E22A5.domain1.po1.104.16E3837.1.5D.1@53
         </gwe:container>
   <gwe:key>GWABEvents</gwe:key>
   <gwe:uid>2284</gwe:uid>
</gwe:event>

Generic events are returned when the following Personal Address Book fields change:

  • Title

  • Department

  • Web site

  • Birthday

  • Comment

  • Type

However, if the following fields are changed, a field element is created that contains the type of field that was changed:

  • Category

  • Contact

  • E-mail address

  • IM address

  • Name

  • Phone number

  • Postal address

For example, if the name on a contact is changed, the following event record is created:

<gwe:event>
   <gwe:event>AddressBookItemModify</gwe:event>
   <gwe:id>438B0F64.domain1.po1.104.16E3837.1.90.1</gwe:id>
   <gwe:timeStamp>2012-11-28T21:39:05Z</gwe:timeStamp>
   <gwe:field>Name</gwe:field>
   <gwe:container>434E22A5.domain1.po1.104.16E3837.1.5D.1@53
       </gwe:container>
   <gwe:key>GWABEvents</gwe:key>
   <gwe:uid>2285</gwe:uid>
</gwe:event>

In this example, the field element contains the Name key word, which tells the listening application that some part of the name in a contact has changed. The listening application now has more information about the particular Personal Address Book change and can act accordingly.

3.3.3 Shared Address Books

Shared address books within a Personal Address Book container are similar to shared folders. When user1 shares an address book with user2, user2 receives a mail item in the In box. User2 can then accept the shared address book.

Applications receive the following events for shared address books:

  • FolderItemAdd: Created for the new mail item in user2’s In box.

Your application can call GetItemsRequest to retrieve the details of the shared address book item. The GetItemsResponse has a SharedNotification attribute, which states that the item is a SharedAddressBook.

<gwe:event>
   <gwe:event>FolderItemAdd</gwe:event>
   <gwe:id>44EC2654.domain1.po1.100.16E3837.1.F76.1</gwe:id>
   <gwe:timeStamp>2012-08-23T15:56:36Z</gwe:timeStamp>
   <gwe:container>7.domain1.po1.100.0.1.0.1@16</gwe:container>
   <gwe:key>GWEvents</gwe:key>
   <gwe:uid>10755</gwe:uid>
   <gwe:type>Mail</gwe:type>
</gwe:event>
<gwt:item xsi:type="gwt:SharedNotification">
   ...
   <gwt:subject>Sharing of Address Book 'New U2 Book'.</gwt:subject>
   ...
   <gwt:notification>SharedAddressBook</gwt:notification>
   <gwt:description>You have been granted shared access to my address
      book named 'New U2 Book'.</gwt:description>
   <gwt:rights>
      <gwt:edit>1</gwt:edit>
   </gwt:rights>
</gwt:item>

When a user accepts the address book, the ItemAccept, ItemModify, and FolderItemMove events are created. These events mark the accepted item as hidden and as moved to the calendar folder, so that your application does not need to track the notification item any more.

<gwe:event>
   <gwe:event>ItemAccept</gwe:event>
   <gwe:id>44EC2654.domain1.po1.100.16E3837.1.F76.1</gwe:id>
   <gwe:timeStamp>2012-08-23T15:58:08Z</gwe:timeStamp>
   <gwe:key>GWEvents</gwe:key>
   <gwe:uid>10758</gwe:uid>
   <gwe:type>Mail</gwe:type>
</gwe:event>
<gwe:event>
   <gwe:event>ItemModify</gwe:event>
   <gwe:id>44EC2654.domain1.po1.100.16E3837.1.F76.1</gwe:id>
   <gwe:timeStamp>2012-08-23T15:58:09Z</gwe:timeStamp>
   <gwe:field>Hidden</gwe:field>
   <gwe:key>GWEvents</gwe:key>
   <gwe:uid>10759</gwe:uid>
   <gwe:type>Mail</gwe:type>
</gwe:event>
<gwe:event>
   <gwe:event>ItemModify</gwe:event>
   <gwe:id>44EC2654.domain1.po1.100.16E3837.1.F76.1</gwe:id>
   <gwe:timeStamp>2012-08-23T15:58:09Z</gwe:timeStamp>
   <gwe:key>GWEvents</gwe:key>
   <gwe:uid>10760</gwe:uid>
   <gwe:type>Mail</gwe:type>
</gwe:event>
<gwe:event>
   <gwe:event>FolderItemMove</gwe:event>
   <gwe:id>44EC2654.domain1.po1.100.16E3837.1.F76.1</gwe:id>
   <gwe:timeStamp>2012-08-23T15:58:09Z</gwe:timeStamp>
   <gwe:container>A.domain1.po1.100.0.1.0.1@19</gwe:container>
   <gwe:from>7.domain1.po1.100.0.1.0.1@16</gwe:from>
   <gwe:key>GWEvents</gwe:key>
   <gwe:uid>10761</gwe:uid>
   <gwe:type>Mail</gwe:type>
</gwe:event>