## CalendarEventLists A **CalendarEventList** is a query on the set of events in a user's calendars. The client can optionally also fetch the events. ### getCalendarEventList To fetch a calendar event list, make a call to *getCalendarEventList*. It takes the following arguments: - **accountId**: `String|null` The id of the account to use for this call. If `null`, the primary account will be used. - **filter**: `FilterCondition|FilterOperator|null` Determines the set of events returned in the results. See the "Filtering" section below for allowed values and semantics. - **position**: `Number|null` The 0-based index of the first result in the list to return, presumed `0` if `null`. If a negative value is given, the call MUST be rejected with an `invalidArguments` error. - **limit**: `Number|null` The maximum number of results to return. If `null`, no limit presumed. The server MAY choose to enforce a maximum `limit` argument. In this case, if a greater value is given (or if it is `null`), the limit should be clamped to the maximum; since the total number of results in the list is returned, the client can determine if it has received all the results. If a negative value is given, the call MUST be rejected with an `invalidArguments` error. - **fetchCalendarEvents**: `Boolean|null` If `true` then after outputting a *calendarEventList* response, an implicit call will be made to *getCalendarEvents* with the `calendarEventIds` array in the response as the *ids* argument. If `false` or `null`, no implicit call will be made. #### Filtering A **FilterOperator** object has the following properties: - **operator**: `String` This MUST be one of the following strings: "AND"/"OR"/"NOT": - **AND**: all of the conditions must match for the filter to match. - **OR**: at least one of the conditions must match for the filter to match. - **NOT**: none of the conditions must match for the filter to match. - **conditions**: `(FilterCondition|FilterOperator)[]` The conditions to evaluate against each event. A **FilterCondition** object has the following properties: - **inCalendars**: `String[]|null` A list of calendar ids. An event must be in ANY of these calendars to match the condition. - **after**: `Date|null` The end of the event, or any recurrence of the event, in UTC time must be after this date to match the condition. - **before**: `Date|null` The start of the event, or any recurrence of the event, in UTC time must be before this date to match the condition. - **text**: `String|null` Looks for the text in the *summary*, *description*, *location*, *organizer*, *attendees* properties of the event or any recurrence of the event (matching either name or email in the organizer/attendee case). - **summary**: `String|null` Looks for the text in the *summary* property of the event, or the overridden *summary* property of a recurrence. - **description**: `String|null` Looks for the text in the *description* property of the event, or the overridden *description* property of a recurrence. - **location**: `String|null` Looks for the text in the *location* property of the event, or the overridden *location* property of a recurrence. - **organizer**: `String|null` Looks for the text in the name or email fields of the *organizer* property of the event, or the overridden *organizer* property of a recurrence. - **attendee**: `String|null` Looks for the text in the name or email of any item in the *attendees* property of the event, or the overridden *attendees* property of a recurrence. If zero properties are specified on the FilterCondition, the condition MUST always evaluate to `true`. If multiple properties are specified, ALL must apply for the condition to be `true` (it is equivalent to splitting the object into one-property conditions and making them all the child of an AND filter operator). The exact semantics for matching `String` fields is **deliberately not defined** to allow for flexibility in indexing implementation, subject to the following: - Text SHOULD be matched in a case-insensitive manner. - Text contained in either (but matched) single or double quotes SHOULD be treated as a **phrase search**, that is a match is required for that exact sequence of words, excluding the surrounding quotation marks. Use `\"`, `\'` and `\\` to match a literal `"`, `'` and `\` respectively in a phrase. - Outside of a phrase, white-space SHOULD be treated as dividing separate tokens that may be searched for separately in the event, but MUST all be present for the event to match the filter. - Tokens MAY be matched on a whole-word basis using stemming (so for example a text search for `bus` would match "buses" but not "business"). #### Sorting Results MUST be sorted in a stable order so the client can load the full list in sections. The exact ordering to use is server dependent. #### Windowing To paginate the results the client MAY supply a *position* argument: this is the 0-based index of the first result to return in the list of events after filtering and sorting. If the index is greater than or equal to the total number of events in the list, then there are no results to return, but this DOES NOT generate an error. If `null`, this defaults to `0`. #### Response The response to a call to *getCalendarEventList* is called *calendarEventList*. It has the following arguments: - **accountId**: `String` The id of the account used for the call. - **filter**: `FilterCondition|FilterOperator|null` The filter of the event list. Echoed back from the call. - **state**: `String` A string encoding the current state on the server. This string will change if the results of the event list MAY have changed (for example, there has been a change to the state of the set of CalendarEvents; it does not guarantee that anything in the list has changed). - **position**: `Number` The 0-based index of the first result in the `calendarEventIds` array within the complete list. - **total**: `Number` The total number of events in the list (given the *filter*). - **calendarEventIds**: `String[]` The list of CalendarEvent ids for each event in the list after filtering and sorting, starting at the index given by the *position* argument of this response, and continuing until it hits the end of the list or reaches the `limit` number of ids. Note, that recurrences are not returned separately in any way; the event only occurs once in the calendarEventIds array no matter how many times it recurs. The following errors may be returned instead of the `calendarEventList` response: `accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account. `accountNoCalendars`: Returned if the *accountId* given corresponds to a valid account, but does not contain any calendar data. `invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A `description` property MAY be present on the response object to help debug with an explanation of what the problem was.