Checking Free/Busy Status

Topic Last Modified: 2006-06-12

Before you send a meeting request, you can check an attendee s calendar to see when the attendee is available. The IAddressee.GetFreeBusy method returns a string of numbers that indicate the attendee's availability for a requested period of time.

Each number in the free/busy string represents an interval of time (every ½ hour in this example). Free time returns 0, Tentative returns 1, Busy returns 2, and Out of Office (OOF) returns 3. If appointments overlap, the highest number is returned. If no free/busy data is available for the interval, the value 4 is returned.

The following figure shows part of an attendee's calendar and the corresponding free/busy string.

To get an attendee's free/busy status for a specific time, you can create an Addressee object and execute the IAddressee.GetFreeBusy method. You can also get the free/busy status for longer intervals and parse the string to find times the attendee is free.

Note

You must first call the IAddressee.CheckName method and resolve the addressee before you can use the IAddressee.GetFreeBusy method.

Note

An automated process in Microsoft® Exchange Server 2007 periodically updates the free/busy status of users. Microsoft Outlook® updates the free/busy status of Outlook users. Collaboration Data Objects (CDO) synchronizes the Outlook free/busy cache with free/busy information from CDO clients. The free/busy status is not updated immediately when a meeting is added to a user's calendar. By default, three months worth of free/busy status is maintained in a system folder in the Exchange store.

This topic contains Microsoft Visual Basic®, Microsoft Visual C++®, Microsoft C#, and Visual Basic .NET code examples.

Example

Visual Basic

The following example returns the free/busy status of the specified user:

' Reference to Microsoft ActiveX Data Objects 2.5 Library
' Reference to Microsoft CDO for Exchange 2000 Library

' Note: It is recommended that all input parameters be validated when they are
' first obtained from the user or user interface.
Function GetFreeBusyString(strUserUPN As String, dtStartDate As Date, dtEndDate As Date, Interval As Integer) As String

    Dim iAddr    As New CDO.Addressee
    Dim freebusy As String
    Dim Info     As New ADSystemInfo

    iAddr.EmailAddress = strUserUPN
    If Not iAddr.CheckName("LDAP://" & Info.DomainDNSName) Then
        ' handle error
    End If

    'Get the free/busy status in Interval minute intervals from dtStartDate to dtEndDate
    freebusy = iAddr.GetFreeBusy(dtStartDate, dtEndDate, Interval)
    GetFreeBusyString = freebusy

End Function

C++

The following example returns the free/busy status of the specified user:

/*
 Assume that the following paths are in your
 INCLUDE path.
 %CommonProgramFiles%\system\ado
 %CommonProgramFiles%\microsoft shared\cdo
*/

#import <msado15.dll> no_namespace
#import <cdoex.dll> no_namespace
#include <iostream.h>

// Note: It is recommended that all input parameters be validated when they are
// first obtained from the user or user interface.
bstr_t getFreeBusyString( const bstr_t& userUPN, const bstr_t& domainDNSName, DATE startDate, DATE endDate, long Interval) {

   IAddresseePtr iAddr(__uuidof(Addressee));

   iAddr->EmailAddress = userUPN;
   if(iAddr->CheckName(bstr_t("LDAP://") + domainDNSName, bstr_t(), bstr_t()) == VARIANT_FALSE) {
      cerr << "Error looking up name!" << endl;
      _com_issue_error(E_FAIL);
   }

    //Get the free/busy status in Interval minute intervals from startDate to endDate
   return iAddr->GetFreeBusy(startDate, endDate, Interval, bstr_t(), bstr_t(), bstr_t(), bstr_t());

}

C#

The following example returns the free/busy status of the specified user:

// Reference to Microsoft ActiveX Data Objects 2.5 Library
// Reference to Microsoft CDO for Exchange 2000 Library
// Reference to Active DS Type Library

// Note: It is recommended that all input parameters be validated when they are
// first obtained from the user or user interface.
static string GetFreeBusyString(string strUserUPN, DateTime dtStartDate,
                                DateTime dtEndDate, int Interval)
{
   try
   {
      // Variables.
      CDO.Addressee iAddr = new CDO.Addressee();
      string freebusy;
      ActiveDs.ADSystemInfo Info = new ActiveDs.ADSystemInfo();

      iAddr.EmailAddress = strUserUPN;
      if  (!(iAddr.CheckName("LDAP://" + Info.DomainDNSName, "", "")))
         throw new System.Exception("Error occured!");

      // Get the free/busy status in Interval minute
      // intervals from dtStartDate to dtEndDate.
      freebusy = iAddr.GetFreeBusy(dtStartDate, dtEndDate,
                                   Interval, "", "", "", "");

      return freebusy;
   }
   catch (Exception err)
   {
      Console.WriteLine(err.ToString());
      return "";
   }
}

Visual Basic .NET

The following example returns the free/busy status of the specified user:

' Reference to Microsoft ActiveX Data Objects 2.5 Library
' Reference to Microsoft CDO for Exchange 2000 Library
' Reference to Active DS Type Library

' Note: It is recommended that all input parameters be validated when they are
' first obtained from the user or user interface.
Function GetFreeBusyString(ByVal strUserUPN As String, ByVal dtStartDate As Date, _
                           ByVal dtEndDate As Date, ByVal Interval As Integer) As String

   Try
      ' Variables.
      Dim iAddr As New CDO.Addressee()
      Dim freebusy As String
      Dim Info As New ActiveDs.ADSystemInfo()

      iAddr.EmailAddress = strUserUPN
      If Not iAddr.CheckName("LDAP://" & Info.DomainDNSName) Then
         Throw New System.Exception("Error occured!")
      End If

     ' Get the free/busy status in Interval minute intervals
     ' from dtStartDate to dtEndDate.
     freebusy = iAddr.GetFreeBusy(dtStartDate, dtEndDate, Interval)
     GetFreeBusyString = freebusy

   Catch err As Exception
      Console.WriteLine(err.ToString())
      GetFreeBusyString = ""
   End Try
End Function