About the Free/Busy API

About the Free/Busy API

The Free/Busy API allows mail providers to provide free/busy status information for specified user accounts within a specified time range. The free/busy status of a block of time on a user's calendar is one of the following: out-of-office, busy, tentative, or free.

Create a Free/Busy Provider

To provide free/busy information to mail users, a mail provider creates a free/busy provider and registers it with Outlook. The free/busy provider must implement the following interfaces. Note that a number of members in these interfaces are not supported and must return the specified return values. In particular, the Free/Busy API does not support write access to free/busy information and delegate access to accounts.

  • IFreeBusySupport. This interface supports specification of interfaces that access free/busy data for specified users. It uses FBUser to identify a user.
  • IFreeBusyData. This interface gets and sets a time range for a given user and returns an interface for enumerating free/busy blocks of data within this time range. It uses relative time to get and set this time range.
  • IEnumFBBlock. This interface supports accessing and enumerating free/busy blocks of data for a user within a time range.
    Bb905126.vs_note(en-us,office.12).gif  Note
    An enumeration contains free/busy blocks that indicate the free/busy status of periods of time on a user's calendar, within a time range (specified by IFreeBusyData::EnumBlocks). Items on a calendar, such as appointments and meeting requests, form blocks in the enumeration. Items adjacent to one another on the calendar having the same free/busy status are combined to form one single block. A free period of time on a calendar also forms a block. Therefore, no two consecutive blocks in an enumeration would have the same free/busy status. These blocks do not overlap in time. When there are overlapping items on a calendar, Outlook merges these items to form non-overlapping free/busy blocks in the enumeration based on this order of precedence: out-of-office, busy, tentative.

To register the free/busy provider with Outlook, the mail provider should:

  1. Register the free/busy provider with COM, providing a CLSID that allows access to the provider's implementation of IFreeBusySupport.
  2. Let Outlook know that the free/busy provider exists by setting this key in the system registry: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\<xx.x>\Outlook\SchedulingInformation\FreeBusySupport where <xx.x> represents the version of Outlook. For example, if the transport provider is SMTP, to register the provider with Microsoft Office Outlook 2007, set the key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\Outlook\SchedulingInformation\FreeBusySupport to the following data:
    Name Type Value
    SMTP REG_SZ {CLSID for respective implementation of IFreeBusySupport}
    In this scenario, Outlook will co-create the COM class and use it to retrieve free/busy information for any SMTP mail users.

To support an address book and transport provider that use an address entry type other than SMTP, change the Name accordingly.

Bb905126.vs_note(en-us,office.12).gif  Note
During installation, free/busy providers should check if a registry setting for the the same address entry type already exists. If it does, the free/busy provider should overwrite the current provider for that address entry type, and restore to that provider when it uninstalls. However, if a user has installed more than one free/busy provider for the same address entry type, the user should uninstall these providers in the reverse order as installation (that is, always uninstall the latest provider), otherwise the registry may point to a provider that has already been uninstalled.

API Components

The Free/Busy API includes the following components:


Constants for the Free/Busy API

Data Types