Sun Java System Calendar Server 6 2005Q4 Developer's Guide

Command: get_freebusy

Purpose

Get the free-busy calendar information for users.

Parameters

Table 7–19 get_freebusy Parameters

Parameter  

Type  

Purpose  

Required  

Default  

busyonly

Integer (0, 1)

0 = return both busy and free periods1 = return only busy periods

1

calid

string 

The calendar identifier. 

he calid can be supplied in two formats: 

  • string - calendar identifier

  • mailto:rfc822addr - An email address appended to “mailto:”. The address is mapped to a user with an LDAP lookup, and then the user’s default calendar ID is used. Returns: X-SICS-EMAIL and X-NSCP-CALPROPS-RELATIVE-CALID

Current user’s default calendar 

dtstart

Date Time string 

Start time of free-busy search. 

N/A 

dtend

Date Time string 

End time of free-busy search. 

N/A 

duration

Integer 

Free busy duration time in number of days. 

60 or Default taken from ics.conf

fmt-out

string 

The format for the returned data. 

Two format types: 

text/calendar

text/xml

text/calendar

freebusybegin

integer 

Offset in number of days from the value of ics.conf setting service.wcap.freebusybegin. Backs off the date range by the value of this parameter. For example, a value of 30 would start the free-busy range 30 days before the current time found in the ics.conf parameter.

Default ics.conf value is 30 (days)

freebusyend

integer 

Offset in number of days from the value of ics.conf setting service.wcap.freebusyend to calculate the end of the free-busy range. Extends the date found in the ics.conf parameter. For example, a value of 30 would put the end date 30 days beyond the current setting.

Default ics.conf value is 30 (days)

id

unique identifier string 

The session identifier. 

N/A 

mail

email address 

An email address used to compute free/busy time. The address must be present in the LDAP. When an email address is passed in, all of the user's eligible calendars are used in computing free-busy time. Eligible calendars are those for which this user is the primary owner and havefbinclude=1.

Y/N 

Either calid or mail must be specified

noredirect

boolean (0, 1)

Parameter passed in with command. When calendar can’t be found in the Calendar Server database, if this parameter is set to 0, the server passes back the redirect URL, if one is present, in the ics.conf parameter service.wcap.freebusy.redirecturl

If this parameter is set to 1, the server does not check for the redirect URL, instead, it returns an error.

0

mail

RFC 822 address 

Can be specified instead of calid. But must be a valid user or group email address in the Calendar Server’s LDAP.

For free-busy lookup, all calendars that have this user as primary owner and have the fbinclude calendar property set to 1 are used in computing free-busy time.

Y/N 

No default. But must be specified if the calid is not specified 

tzid

time zone-ID string 

Default time zone to use if dtstart, or dtend parameters do not have a time zone specified.

For example, “America/Los_Angeles” 

Server’s default time zone 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

Description

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:

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

Error Codes

If this command fails for any reason, errno is set to Error Codes(39).

Example

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