Get the free-busy calendar information for users.
This command retrieves the free-busy calendar information for specified users. Free-busy calendar information indicates which times have been scheduled on the user's calendar. Free-busy calendar information does not include any details of the scheduled time.
Free-busy time is calculated for a time period that can be specified in one of three ways:
duration parameter
The default value of the duration parameter is taken from the ics.conf setting service.wcap.freebusyduration. The standard default is 60 days. This is the default taken if none of the time period parameters are passed in.
dtstart and dtend parameters
The absolute start and end times to use for this free-busy calculation. These parameters have no default values.
freebusybegin and freebusyend parameters.
The relative beginning and end times to include in the free-busy calculation. If these are specified with no value, the default is 30 for each.
If conflicting parameters are passed in, the duration parameter overrides the other two types.
For further information about how free-busy calendars are specified, see Free-Busy Calendars in Calendar Server WCAP
At fetch time, the server looks at the free-busy value in the event structure. If the value exists, it emits it as X-S1CS-FBTYPE. If the value does not exist, that is, the value was not stored with the event, the server calculates the value for X-S1CS-FBTYPE using the algorithm shown in the following table.
PARSTAT Value |
TRANSPARENCY Value |
|
---|---|---|
None specified, or OPAQUE |
TRANSPARENT |
|
TENTATIVE |
Busy-tentative |
Free |
ACCEPTED |
Busy |
Free |
DECLINED |
Free |
Free |
NEEDS-ACTION |
Busy-tentative |
Free |
For overlapping events that do not have the same free-busy types, the system returns the value based on the following precedence rules: Busy overrides Busy-tentative, Busy-tentative overrides Free.
If this command fails for any reason, errno is set to 39.
For example, a calendar called jdoe has the following events:
10:00-11:00 |
first meeting |
12:00-1:00 |
lunch |
3:00-4:00 |
second meeting |
The free-busy time for jdoe (from 9:00 to 6:00) would be the following:
9:00-10:00 |
Free |
10:00-11:00 |
Busy |
11:00-12:00 |
Free |
12:00-1:00 |
Busy |
1:00-3:00 |
Free |
3:00-4:00 |
Busy |
4:00-6:00 |
Free |
The following URL generates free-busy information found in the calendar jdoe between May 1, 2002 and July 1, 2002.
The output is returned in text/calendar format.
http://calendarserver/get_freebusy.wcap ?id=2mu95r5so0hq68ts6q3 &calid=jsun &dtstart=20020501T112233Z &dtend=20020701T112233Z &fmt-out=text/calendar
Here is the output:
BEGIN:VCALENDAR PRODID:-//SunONE/Calendar Hosting Server//EN METHOD:PUBLISH VERSION:6.0 X-NSCP-CALPROPS-LAST-MODIFIED:20010517T012259Z X-NSCP-CALPROPS-CREATED:20010517T012259Z X-NSCP-CALPROPS-READ:999 X-NSCP-CALPROPS-WRITE:999 X-NSCP-CALPROPS-DESCRIPTION:Work Calendar for John Doe X-NSCP-CALPROPS-RELATIVE-CALID:jdoe X-NSCP-CALPROPS-NAME:John Doe X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe X-NSCP-CALPROPS-OWNERS:susan X-NSCP-CALPROPS-CATEGORIES:business X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^S^g BEGIN:VFREEBUSY DTSTART:20020501T112233Z DTEND:20020701T112233Z FREEBUSY;FBTYPE=FREE:20020501T112233Z/20020518T170000Z FREEBUSY;FBTYPE=BUSY:20020518T170000Z/20020518T190000Z FREEBUSY;FBTYPE=FREE:20020518T190000Z/20020525T170000Z FREEBUSY;FBTYPE=BUSY:20020525T170000Z/20020525T190000Z FREEBUSY;FBTYPE=FREE:20020525T190000Z/20020601T170000Z FREEBUSY;FBTYPE=BUSY:20020601T170000Z/20020601T190000Z FREEBUSY;FBTYPE=FREE:20020601T190000Z/20020608T170000Z FREEBUSY;FBTYPE=BUSY:20020608T170000Z/20020608T190000Z FREEBUSY;FBTYPE=FREE:20020608T190000Z/20020615T170000Z FREEBUSY;FBTYPE=BUSY:20020615T170000Z/20020615T190000Z FREEBUSY;FBTYPE=FREE:20020615T190000Z/20020622T170000Z FREEBUSY;FBTYPE=BUSY:20020622T170000Z/20020622T190000Z FREEBUSY;FBTYPE=FREE:20020622T190000Z/20020629T170000Z FREEBUSY;FBTYPE=BUSY:20020629T170000Z/20020629T190000Z FREEBUSY;FBTYPE=FREE:20020629T190000Z/20020701T112233Z END:VFREEBUSY X-NSCP-WCAP-ERRNO:0 END:VCALENDAR