Managing personal address books containers and manipulating items within the personal address book containers is different, as shown in the following sections:
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.
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:
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.
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.
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.
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>