GetFreeBusy Method (AddressEntry Object)
GetFreeBusy Method (AddressEntry Object)
The GetFreeBusy method returns a string representing the availability of the messaging user for a meeting over a specified period of time.
Syntax
strAvail = objAddressEntry.GetFreeBusy(StartTime, EndTime, Interval)
strAvail
On successful return, contains a string indicating the messaging user's availability for each of the time slots in the specified time period.
objAddressEntry
Required. The AddressEntry object.
StartTime
Required. Variant (vbDate format). Specifies the date/time of the beginning of the first time slot.
EndTime
Required. Variant (vbDate format). Specifies the date/time of the end of the last time slot.
Interval
Required. Long. Specifies the length of each time slot in minutes. If this parameter is less than 1, GetFreeBusy returns CdoE_INVALID_PARAMETER.
Remarks
The returned string length equals the number of time slots between StartTime and EndTime. Each character is the ASCII representation of the appropriate type library constant indicating the messaging user's availability during a time slot:
ASCII character |
Corresponding type library constant |
Meaning |
"0" |
CdoFree |
Available for appointments or meetings throughout the time slot |
"1" |
CdoTentative |
At least one tentative commitment during the time slot |
"2" |
CdoBusy |
At least one confirmed commitment during the time slot |
"3" |
CdoOutOfOffice |
Designated as out-of-office (OOF) for at least part of the time slot |
If there is any overlapping of commitments during a time slot, GetFreeBusy returns the most committed state, that is, the highest character value. For example, if a messaging user already has one tentative meeting and one confirmed meeting scheduled during the same time slot, GetFreeBusy returns "2" for that time slot, corresponding to CdoBusy. CdoFree is not returned unless the entire time slot is free of commitments.
For performance reasons, calendaring clients typically do not publish appointments indefinitely into the future. For example, the CDO Library, Microsoft® Outlook®, Microsoft® Schedule+, and Microsoft Outlook Web Access (OWA) all publish appointments for a default maximum of three months including the current date. You can change this maximum by supplying "FreeBusyMonths" in the OptType parameter of the Session object's SetOption method.
The free/busy information is always published from the beginning of the current month. A consequence of this is that when the date is near the end of the current month, GetFreeBusy effectively returns future appointment information for one month less than the "FreeBusyMonths" option indicates.
If you call GetFreeBusy on a messaging user and specify time slots occupying more months than "FreeBusyMonths" allows, GetFreeBusy is likely to return CdoFree for every time slot past the maximum. Unless you are familiar with the behavior and publishing limits of a messaging user's calendaring client, you should not interpret CdoFree as meaning that the user is genuinely free for a time slot significantly in the future.
When a messaging user creates an appointment using Outlook, the calendar is not updated until logoff from Outlook. This means that changes to that user's free/busy information are not available to other messaging users until the Outlook user logs off.
When a messaging user's mailbox is first created using either Outlook or a CDO application, its free/busy information is not initialized until the user calls a method, such as GetDefaultFolder or GetFreeBusy, that initializes this information. If another messaging user calls GetFreeBusy on that user before the free/busy information is initialized, CDO returns CdoE_NOT_FOUND. This is not the case with a Schedule+ mailbox, which initializes its free/busy information immediately upon creation.
If an address entry represents a distribution list, the status of its individual members cannot be returned to you. A meeting request should be sent only to single messaging users. You can determine if a messaging user is a distribution list by checking its DisplayType property.