Web Services

The Availability operations improve information workers' calendar and free/busy sharing experience by providing secure, up-to-date, and rich free/busy information. This information enables developers to create sophisticated collaboration and scheduling applications.

The Availability Web service provides tools to create enhanced Exchange 2007 client applications by doing the following:

• Retrieving live free/busy information for Exchange 2007 mailboxes.
• Retrieving live free/busy information from other Exchange 2007 forests.
• Retrieving published free/busy information from public folders.
• Retrieving suggested meeting times.
• Supplying up-to-date free/busy data so that users and resources can be scheduled with more confidence.
• Supplying more specific data that describes the status of users and resources, such as the start times and the end times of individual appointments, subjects, locations, work hours, and so on.
• Securing the distribution of free/busy data by specifying the level of detail to share with specified users.

In addition, the Availability operations enable users to share their calendar information in more granular ways. For each target person/group, the user can select one of four levels of sharing:

• Share nothing
• Share their free/busy information
• Share more detail including subject, location, and timing
• Share full calendar details

Starting with Exchange 2007 SP1, delegate management is available through Exchange Web Services. Four Exchange Web Services operations provide delegate management functionality. These operations enable you to do the following:

• Add new delegates.
• Retrieve and update existing delegate permissions.
• Remove existing delegates.

Delegate access supports the following types of scenarios:

• Delegates can open the folders of a principal and manipulate items based on folder-level permissions.
• Delegates can create and send meeting messages on behalf of the principal.
• Delegates can receive meeting messages that are forwarded by the principal and respond to them for the principal.
• Users who have owner rights on a shared mailbox can open the mailbox and act as the owner.
• Delegates can create notification subscriptions on folders in the mailbox of the principal.

The Folder operations provide access to folders in the Exchange data store. A client application can create, update, delete, copy, find, get, and move folders that are associated with a mailbox user. Folders are used to gain access to items in the store, and provide a reference container for items in the store.

The folder operations enable client applications to do the following:

• Get the identity of a single folder.
• Identify which folder properties are returned by a request.
• Enumerate the items or folders that are descendants of a single folder.
• Access data fields in an item or folder.
• Search a folder hierarchy.
• Use search restrictions to narrow the response set.
• Create search folders.
• Provide support for delegate and administrative access to items and folders in the store.

The Item operations provide access to items in the Exchange data store. By using these operations, a client application can create, update, delete, copy, get, move, and send items. The Item operations work on the following item types:

• Message Items   Message items are XML representations of the Internet Message Format defined in [RFC2822] that are defined in e-mail messages.
• Contact Items   Contact items are a set of properties that represent contacts that are located either in the Active Directory directory service or in private contact stores. It is important to note that, while these two types of contacts are similar in data content, they differ in the types of operations that you can perform on them.
• Task Items   Task items are the Outlook Personal Information Manager (PIM) objects that can be accessed by the Task pane. Tasks can be single items or recurring activities.
• Calendar Items   Calendar items identify the location, resources, recurrence, and attendees involved at a discrete time. Calendar items are represented by Meetings, Appointments, Meeting Invitations, and Invitation-handling objects. Meeting organizers can create, update, and delete both individual and recurring meetings. Organizers can also send out meeting invitations. Meeting attendees can accept, decline, and acknowledge the receipt of invitations and counter-propose a time or recurring schedule for a meeting.

The Messaging Records Management operation enables the assignment of managed custom folders to mailbox users. Client applications that consume this Web service give users the ability to add managed custom folders to their mailbox instead of having an administrator perform the task. Administrators in large organizations do not have the resources to set up user subscriptions to policy folders. Frequently, administrators do not know which policy folders an individual user should use. Users can subscribe to individual policy folders. This works in addition to policy folders assigned to groups of users by the administrators.

The Notification operations notify client systems of events and changes in mailboxes on computers that are running Exchange 2007. Clients subscribe for notifications to the Event Notifications subsystem, and specify the types of events to monitor on the specified mailboxes. The Notification operations provide push and pull subscriptions from the Exchange 2007 computer that is running the Client Access server role. The following are the events that are monitored by the Event Notification subsystem:

• Mail arrival
• Item creation
• Item deletion
• Item modification
• Item movement
• Item copied
• Mail submission

The Synchronization operations provide a one-way, synchronized cached copy of a user's folders and items. This Web service provides two forms of synchronization:

1. Folder Hierarchy   A client synchronizes the folder hierarchy of a whole mailbox or any subfolder hierarchy within the mailbox.
2. Folder Items   A client synchronizes all items in a folder.

Clients can also explicitly ignore items so that they are not synchronized, and specify how many items should be synchronized between server and client.

The Utility operations enable client applications to resolve ambiguous names and return the membership of a distribution list.

Starting with Exchange 2007 SP1, the schema includes a SOAP header element that is used to version SOAP requests. The SOAP header is required to identify the schema against which client requests are validated and upon which the server's response is based.

Starting with Exchange 2007 SP1, you can use Exchange Web Services operations to access public folders. This includes the following functionality:

• Access to the public folder hierarchy
• Access to detailed information about public folders
• Access to detailed information about public folder items
• The ability to post items
• The ability to synchronize public folder items
• Subscription notifications for public folders

Starting with Exchange 2007 SP1, Exchange Web Services provides folder-level permissions. You can access and set these permissions by using the CreateFolder, GetFolder, UpdateFolder, and SyncFolderHierarchy operations. This includes the following functionality:

• Clients can query and configure the sharing of permissions on the folder.
• Clients can retrieve the effective rights to get the effective permission for the logon user.
• Free/busy calendar folder permissions are exposed.

Starting with Exchange 2007 SP1, you can use the ConvertId operation to convert different item identifiers. The ConvertId operation supports public folders, mailbox folders, and item identifiers. The following are the supported identifier formats:

• The initial release of Exchange 2007 Exchange Web Services identifiers. These are the identifiers that Exchange Web Services creates and consumes for folders and items in Exchange 2007.
• Exchange Web Services SP1 or Exchange Web Services SP2 identifiers. These are the identifiers that Exchange Web Services creates and consumes for folders and items in Exchange 2007 SP1 and Exchange 2007 SP2.
• EntryID identifiers. These are provided by MAPI components.
• Outlook Web Access identifiers. These are the identifiers that are created by Outlook Web Access and offered to consumers in the query string of the Outlook Web Access URL.
• Availability Calendar ID identifiers. These identifiers are hexadecimal-encoded entry IDs that are used by the Availability feature to represent calendar items in a GetUserAvailability response.

Starting with Exchange 2007 SP1, the format of Exchange Web Services identifiers for folders and items differs from the format of identifiers in the initial release version of Exchange 2007. In Exchange 2007, the primary SMTP address is embedded in the identifier format. Because primary SMTP addresses can change, identifiers that are cached on a client will not match identifiers of items on the server if the primary SMTP address is updated, and attempts to reference the item will fail. In Exchange 2007 SP1 and Exchange 2007 SP2, the identifiers encode a mailbox identifier instead of the primary SMTP address to uniquely identify the item or folder.

If an Exchange 2007 client sends requests against a computer that is running Exchange 2007 SP1 or Exchange 2007 SP2, the identifier will work unless the SMTP address has changed. If the SMTP address has changed, the Exchange 2007 client must resynchronize.