Using Delegate Access with Exchange Web Services

Ad hoc FindItem and FindFolder operation searches are used as the entry point for delegate access to the mailbox of a principal. These operations identify parent folders that are searched. If the caller is using delegate access, the parent folders that are searched are located in the mailbox of the principal, instead of the mailbox of the caller.

Listing 1 shows a partial XML request to search the mailboxes of two principals.

Listing 1   Request to search user1's Junk E-mail folder and user2's Inbox folder

<FindItem Traversal="Shallow">
  <ItemShape>
    <t:BaseShape>IdOnly</t:BaseShape>
  </ItemShape>
  <ParentFolderIds>
    <t:DistinguishedFolderId Id="junkemail">
      <t:Mailbox>
        <t:EmailAddress>user1@example.com</t:EmailAddress>
      </t:Mailbox>
    </t:DistinguishedFolderId>
    <t:DistinguishedFolderId Id="inbox">
      <t:Mailbox>
        <t:EmailAddress>user2@example.com</t:EmailAddress>
      </t:Mailbox>
    </t:DistinguishedFolderId>
  </ParentFolderIds>
</FindItem>

The Mailbox child element of the DistinguishedFolderId element signifies that a delegate is performing the FindItem request. If the Mailbox elements were removed from this request, the FindItem search would be performed on the caller's Junk E-mail and Inbox folders. Because the Mailbox elements are included, the request represents an attempt by the caller to act as a delegate to search the mailboxes of the two principals, user1 and user2.

Listing 2 shows you how to perform this search by using the proxy objects.

Listing 2    Partial FindItem request for delegate access

FindItemType request = new FindItemType();
DistinguishedFolderIdType[] folders = new DistinguishedFolderIdType[2];
folders[0].Id = DistinguishedFolderIdNameType.junkemail;
folders[0].Mailbox = new EmailAddressType();
folders[0].Mailbox.EmailAddress = "user1@example.com";
folders[1].Id = DistinguishedFolderIdNameType.inbox;
folders[1].Mailbox = new EmailAddressType();
folders[1].Mailbox.EmailAddress = "user2@example.com";
request.ParentFolderIds = folders;

OK, so now you need to understand what is returned in a delegate access response. And more importantly, how delegate access is implemented.

Exchange Web Services interprets a request that contains the Mailbox element as a child element of the DistinguishedFolderId element as a request for delegate access. When it receives this kind of request, Exchange Web Services first determines whether the caller has act as owner permissions. If the caller has act as owner permissions, Exchange Web Services opens the mailbox as expected. Otherwise, it opens the mailbox as a delegate and the Exchange store performs access checks on each operation that the Exchange Web Services client performs.

The proxy object response to a delegate access FindItem request will contain one FindItemResponseMessageType per folder searched. In Listing 3, two FindItemResponseMessageType objects are represented by the FindItemResponseMessage element. These two elements represent the two folders that are identified to be searched in the request. The FindItemResponseMessageType order is determined by the order in which the folders were serialized. In the previous example, we identified user1's Junk E-mail folder first, therefore it will be the first FindItemResponseMessageType in the response. This is important when the delegate has to distinguish item ownership. Listing 3 shows you the XML in the response. Notice that there are two folders that have a single item in each one.

Listing 3   The FindItemResponse for a delegate access search of two folders in two different mailboxes

<FindItemResponse>
  <ResponseMessages xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
    <FindItemResponseMessage ResponseClass="Success">
      <ResponseCode>NoError</ResponseCode>
      <RootFolder IncludesLastItemInRange="true" TotalItemsInView="1">
        <Items xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
          <MeetingRequest>
            <ItemId Id="AAArAG1za2lgAA" ChangeKey="CwAAABYAAAAMoHzy8/" />
          </MeetingRequest>
        </Items>
      </RootFolder>
    </FindItemResponseMessage>
    <FindItemResponseMessage ResponseClass="Success">
      <ResponseCode>NoError</ResponseCode>
      <RootFolder IncludesLastItemInRange="true" TotalItemsInView="1">
        <Items xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
          <MeetingRequest>
            <ItemId Id="AAAnAHJheWRAbW" ChangeKey="CwAAABYZAG6tPNDn" />
          </MeetingRequest>
        </Items>
      </RootFolder>
    </FindItemResponseMessage>
  </ResponseMessages>
</FindItemResponse>

We have seen the XML for the request and the XML deserialized from the response. But how does this all work when you are using the proxy objects? (For information about proxy objects, see Introduction to Exchange Web Services in Exchange 2007, Part 3).

Let's take a look at Listing 4. The code example in Listing 4 performs the same delegate access operation that is performed in Listing 1 and Listing 3. It shows an attempt to search the mailboxes of two principals.

Listing 4   An attempt to perform a delegate access search of two mailboxes

static void FindItems(ExchangeServiceBinding esb)
{
    // Form the FindItem request.
    FindItemType findItemRequest = new FindItemType();

    // Define which item properties are returned in the response.
    ItemResponseShapeType itemProperties = new ItemResponseShapeType();
    // Use the Default shape for the response. 
    itemProperties.BaseShape = DefaultShapeNamesType.IdOnly;
    findItemRequest.ItemShape = itemProperties;

    DistinguishedFolderIdType[] folderIDArray = new DistinguishedFolderIdType[2];
    folderIDArray[0] = new DistinguishedFolderIdType();
    folderIDArray[0].Id = DistinguishedFolderIdNameType.junkemail;
    folderIDArray[0].Mailbox = new EmailAddressType();
    folderIDArray[0].Mailbox.EmailAddress = " user1@example.com ";
    folderIDArray[1] = new DistinguishedFolderIdType();
    folderIDArray[1].Id = DistinguishedFolderIdNameType.inbox;
    folderIDArray[1].Mailbox = new EmailAddressType();
    folderIDArray[1].Mailbox.EmailAddress = " user2@example.com ";

    findItemRequest.ParentFolderIds = folderIDArray;

    // Define the traversal type.
    findItemRequest.Traversal = ItemQueryTraversalType.Shallow;

    try
    {
        // Send the FindItem request and get the response.
        FindItemResponseType findItemResponse = esb.FindItem(findItemRequest);

        // Access the response message.
        ArrayOfResponseMessagesType responseMessages = findItemResponse.ResponseMessages;
        ResponseMessageType[] rmta = responseMessages.Items;

        int folderNumber = 0;

        foreach (ResponseMessageType rmt in rmta)
        {
            // One FindItemResponseMessageType per folder searched.
            FindItemResponseMessageType firmt = rmt as FindItemResponseMessageType;

            FindItemParentType fipt = firmt.RootFolder;
            object obj = fipt.Item;

            // FindItem contains an array of items.
            if (obj is ArrayOfRealItemsType)
            {
                ArrayOfRealItemsType items = (obj as ArrayOfRealItemsType);
                if (items.Items == null)
                {
                    Console.WriteLine("Folder {0}: No items in folder", folderNumber);
                    folderNumber++;
                }
                else
                {
                    foreach (ItemType it in items.Items)
                    { 
                        Console.WriteLine("Folder {0}: Item identifier: {1}", folderNumber, it.ItemId.Id);

                    }
                    
                    folderNumber++;
                }
            }
        }
        Console.ReadLine();
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
    }
}