Documentation

Kronolith_Api extends Horde_Registry_Api
in package

Kronolith

Kronolith external API interface.

This file defines Kronolith's external API interface. Other applications can interact with Kronolith through this API.

$_links : array<string|int, mixed>: Links.
addCalendar() : string: Create a new calendar for the existing user.
browse() : array<string|int, mixed>: Browse through Kronolith's object tree.
checkLocks() : mixed: Check for existing calendar or event locks.
delete() : mixed: Deletes an event identified by UID.
deleteCalendar() : mixed: Delete the specified calendar.
eventFromUID() : Kronolith_Event: Retrieves a Kronolith_Event object, given an event UID.
export() : string: Exports an event, identified by UID, in the requested content type.
exportCalendar() : string: Exports a calendar in the requested content type.
getActionTimestamp() : int: Returns the timestamp of an operation for a given uid an action
getAttachment() : array<string|int, mixed>: Return an event attachment.
getCalendar() : Kronolith_Calendar: Return an internal calendar.
getChanges() : array<string|int, mixed>: Method for obtaining all server changes between two timestamps. Basically a wrapper around listBy(), but returns an array containing all adds, edits and deletions. If $ignoreExceptions is true, events representing recurring event exceptions will not be included in the results.
getChangesByModSeq() : array<string|int, mixed>: Return all changes occuring between the specified modification sequences.
getDefaultShare() : string: Retrieve the UID for the current user's default calendar.
getFbCalendars() : array<string|int, mixed>
getFreeBusy() : Horde_Icalendar_Vfreebusy: Generates free/busy information for a given time period.
getHighestModSeq() : int: Return the largest modification sequence from the history backend.
import() : array<string|int, mixed>: Imports an event represented in the specified content type.
listBy() : array<string|int, mixed>: Returns an array of UIDs for events that have had $action happen since $timestamp.
listCalendars() : array<string|int, mixed>: Returns all calendars a user has access to, according to several parameters/permission levels.
listEvents() : array<string|int, mixed>: Lists events for a given time period.
listTagInfo() : array<string|int, mixed>: Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.
listUids() : array<string|int, mixed>: Returns the ids of all the events that happen within a time period.
lock() : mixed: Places an exclusive lock for a calendar or an event.
lookupFreeBusy() : mixed: Attempt to lookup the free/busy information for the given email address.
modified() : int: Returns the last modification timestamp for the given uid.
move() : mixed: Move an event.
path_delete() : mixed: Deletes a file from the Kronolith tree.
put() : array<string|int, mixed>: Saves a file into the Kronolith tree.
quickAdd() : array<string|int, mixed>: Imports an event parsed from a string.
replace() : mixed: Replaces the event identified by UID with the content represented in the specified contentType.
searchTags() : array<string|int, mixed>: SearchTags API: Returns an application-agnostic array (useful for when doing a tag search across multiple applications)
shareHelp() : string: Returns the share helper prefix
sources() : array<string|int, mixed>: Returns a list of available sources.
subscribe() : mixed: Subscribe to a calendar.
unlock() : mixed: Releases a lock.
unsubscribe() : mixed: Unsubscribe from a calendar.
updateAttendee() : mixed: Updates an attendee's response status for a specified event.
updateCalendar() : mixed: Update an internal calendar's information.
_addiCalEvent() : string: Imports a single vEvent part to storage.

$_links

Links.


    protected
        array<string|int, mixed>
    $_links
     = array('show' => '%application%/event.php?calendar=|calendar|&eventID=|event|&uid=|uid|')

addCalendar()

Create a new calendar for the existing user.


    public
                    addCalendar(string $name[, array<string|int, mixed> $params = array() ]) : string

Parameters

$name : string: The calendar's display name.
$params : array<string|int, mixed> = array()

Return values

string —

The new calendar's UID.

browse()

Browse through Kronolith's object tree.


    public
                    browse([string $path = '' ][, array<string|int, mixed> $properties = array() ]) : array<string|int, mixed>

Parameters

$path : string = '': The level of the tree to browse.
$properties : array<string|int, mixed> = array(): The item properties to return. Defaults to 'name', 'icon', and 'browseable'.

Return values

array<string|int, mixed> —

The contents of $path

checkLocks()

Check for existing calendar or event locks.


    public
                    checkLocks(array<string|int, mixed> $calendar[, array<string|int, mixed> $event = null ]) : mixed

Parameters

$calendar : array<string|int, mixed>: The calendar to check locks for.
$event : array<string|int, mixed> = null: The event to check locks for.

Return values

mixed —

delete()

Deletes an event identified by UID.


    public
                    delete(string|array<string|int, mixed> $uid[, mixed $recurrenceId = null ][, string $range = null ]) : mixed

Parameters

$uid : string|array<string|int, mixed>: A single UID or an array identifying the event(s) to delete.
$recurrenceId : mixed = null: The reccurenceId for the event instance, if this is a deletion of a recurring event instance ($uid must not be an array). Either a string or Horde_Date object.
$range : string = null: The range value if deleting a recurring event instance. Only supported values are null or Kronolith::RANGE_THISANDFUTURE. @since 4.1.5

Return values

mixed —

deleteCalendar()

Delete the specified calendar.


    public
                    deleteCalendar(string $id) : mixed

Parameters

$id : string: The calendar id.

Return values

mixed —

eventFromUID()

Retrieves a Kronolith_Event object, given an event UID.


    public
                    eventFromUID(string $uid[, mixed $calendar = null ]) : Kronolith_Event

Parameters

$uid : string: The event's UID.
$calendar : mixed = null

Return values

Kronolith_Event —

A valid Kronolith_Event.

export()

Exports an event, identified by UID, in the requested content type.


    public
                    export(string $uid, string $contentType[, array<string|int, mixed> $options = array() ][, array<string|int, mixed> $calendars = null ]) : string

Parameters

$uid : string

Identify the event to export.

$contentType : string

What format should the data be in? A string with one of:

 text/calendar (VCALENDAR 2.0. Recommended as
                this is specified in rfc2445)
 text/x-vcalendar (old VCALENDAR 1.0 format.
                  Still in wide use)
 activesync (Horde_ActiveSync_Message_Appointment)

$options : array<string|int, mixed> = array()

Any additional options to be passed to the exporter.

$calendars : array<string|int, mixed> = null

Require event to be in these calendars. @since 4.2.0

Return values

string —

The requested data.

exportCalendar()

Exports a calendar in the requested content type.


    public
                    exportCalendar(string $calendar, string $contentType) : string

Parameters

$calendar : string

The calendar to export.

$contentType : string

What format should the data be in? A string with one of:

text/calendar (VCALENDAR 2.0. Recommended as
               this is specified in rfc2445)
text/x-vcalendar (old VCALENDAR 1.0 format.
                 Still in wide use)

Return values

string —

The iCalendar representation of the calendar.

getActionTimestamp()

Returns the timestamp of an operation for a given uid an action


    public
                    getActionTimestamp(string $uid, string $action[, string $calendar = null ][, bool $modSeq = false ]) : int

Parameters

$uid : string: The uid to look for.
$action : string: The action to check for - add, modify, or delete.
$calendar : string = null: The calendar to search in.
$modSeq : bool = false: Request a modification sequence instead of a timestamp. @since 4.1.1

Return values

int —

The timestamp or modseq for this action.

getAttachment()

Return an event attachment.


    public
                    getAttachment(string $calendar, string $uid, string $filename) : array<string|int, mixed>

Parameters

$calendar : string: The calendar ID.
$uid : string: The UID of the event the file is attached to.
$filename : string: The name of the file.

Return values

array<string|int, mixed> —

An array containing the following keys: data (stream): A file pointer to the attachment data. content-type (string): The mime-type of the contents.

getCalendar()

Return an internal calendar.


    public
                    getCalendar([string $id = null ]) : Kronolith_Calendar

Parameters

$id : string = null: The calendar uid (share name).

Return values

Kronolith_Calendar —

The calendar object.

getChanges()

Method for obtaining all server changes between two timestamps. Basically a wrapper around listBy(), but returns an array containing all adds, edits and deletions. If $ignoreExceptions is true, events representing recurring event exceptions will not be included in the results.


    public
                    getChanges(int $start, int $end[, bool $ignoreExceptions = true ][, bool $isModSeq = false ][, string|array<string|int, mixed> $calendars = null ]) : array<string|int, mixed>

Parameters

$start : int: The starting timestamp
$end : int: The ending timestamp.
$ignoreExceptions : bool = true: Do not include exceptions in results.
$isModSeq : bool = false: If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1
$calendars : string|array<string|int, mixed> = null: The sources to check. @since 4.2.0

Return values

array<string|int, mixed> —

An hash with 'add', 'modify' and 'delete' arrays.

getChangesByModSeq()

Return all changes occuring between the specified modification sequences.


    public
                    getChangesByModSeq(int $start, int $end[, string|array<string|int, mixed> $calendars = null ]) : array<string|int, mixed>

Parameters

$start : int: The starting modseq.
$end : int: The ending modseq.
$calendars : string|array<string|int, mixed> = null: The sources to check. @since 4.2.0

Return values

array<string|int, mixed> —

The changes @see getChanges()

getDefaultShare()

Retrieve the UID for the current user's default calendar.


    public
                    getDefaultShare() : string

Return values

string —

UID.

getFbCalendars()


    public
                    getFbCalendars() : array<string|int, mixed>

Return values

array<string|int, mixed> —

A list of calendars used to display free/busy information

getFreeBusy()

Generates free/busy information for a given time period.


    public
                    getFreeBusy([int $startstamp = null ][, int $endstamp = null ][, string $calendar = null ]) : Horde_Icalendar_Vfreebusy

Parameters

$startstamp : int = null: The start of the time period to retrieve.
$endstamp : int = null: The end of the time period to retrieve.
$calendar : string = null: The calendar to view free/busy slots for. Defaults to the user's default calendar.

Return values

Horde_Icalendar_Vfreebusy —

A freebusy object that covers the specified time period.

getHighestModSeq()

Return the largest modification sequence from the history backend.


    public
                    getHighestModSeq([string $id = null ]) : int

Parameters

$id : string = null: The calendar id to return the hightest MDOSEQ for. If null, the highest MODSEQ across all calendars is returned. @since 4.2.0

Return values

int —

The MODSEQ value.

import()

Imports an event represented in the specified content type.


    public
                    import(string $content, string $contentType[, string $calendar = null ][, bool $hash = false ]) : array<string|int, mixed>

Parameters

$content : string

The content of the event.

$contentType : string

What format is the data in? Currently supports:

text/calendar
text/x-vcalendar
activesync

$calendar : string = null

What calendar should the event be added to?

$hash : bool = false

If true, return a hash for EAS additions. @since 4.3.0 @todo Remove for 5.0 and make this the normal return.

Return values

array<string|int, mixed> —

The event's UID.

listBy()

Returns an array of UIDs for events that have had $action happen since $timestamp.


    public
                    listBy(string $action, int $timestamp[, string $calendar = null ][, int $end = null ][, bool $isModSeq = false ]) : array<string|int, mixed>

Parameters

$action : string: The action to check for - add, modify, or delete.
$timestamp : int: The time to start the search.
$calendar : string = null: The calendar to search in.
$end : int = null: The optional ending timestamp
$isModSeq : bool = false: If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1

Return values

array<string|int, mixed> —

An array of UIDs matching the action and time criteria.

listCalendars()

Returns all calendars a user has access to, according to several parameters/permission levels.


    public
                    listCalendars([bool $owneronly = false ][, int $permission = null ]) : array<string|int, mixed>

Parameters

$owneronly : bool = false: Only return calendars that this user owns? Defaults to false.
$permission : int = null: The permission to filter calendars by.

Return values

array<string|int, mixed> —

The calendar list.

listEvents()

Lists events for a given time period.


    public
                    listEvents([int $startstamp = null ][, int $endstamp = null ][, array<string|int, mixed> $calendars = null ][, bool $showRecurrence = true ][, bool $alarmsOnly = false ][, bool $showRemote = true ][, bool $hideExceptions = false ][, bool $coverDates = true ][, mixed $fetchTags = false ]) : array<string|int, mixed>

Parameters

$startstamp : int = null: The start of the time period to retrieve.
$endstamp : int = null: The end of the time period to retrieve.
$calendars : array<string|int, mixed> = null: The calendars to view events from. Defaults to the user's default calendar.
$showRecurrence : bool = true: Return every instance of a recurring event? If false, will only return recurring events once inside the $startDate - $endDate range.
$alarmsOnly : bool = false: Filter results for events with alarms. Defaults to false.
$showRemote : bool = true: Return events from remote calendars and listTimeObject API as well?
$hideExceptions : bool = false: Hide events that represent exceptions to a recurring event (events with baseid set)?
$coverDates : bool = true: Add multi-day events to all dates?
$fetchTags : mixed = false

Return values

array<string|int, mixed> —

A list of event hashes.

listTagInfo()

Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.


    public
                    listTagInfo([array<string|int, mixed> $tags = null ][, string $user = null ]) : array<string|int, mixed>

Parameters

$tags : array<string|int, mixed> = null: An optional array of tag_ids. If omitted, all tags will be included.
$user : string = null: Restrict result to those tagged by $user.

Return values

array<string|int, mixed> —

An array containing tag_name, and total

listUids()

Returns the ids of all the events that happen within a time period.


    public
                    listUids([string|array<string|int, mixed> $calendars = null ], object $startstamp, object $endstamp) : array<string|int, mixed>

Only includes recurring events once per time period, and does not include events that represent exceptions, making this method useful for syncing purposes. For more control, use the listEvents method.

Parameters

$calendars : string|array<string|int, mixed> = null: The calendar to check for events.
$startstamp : object: The start of the time range.
$endstamp : object: The end of the time range.

Return values

array<string|int, mixed> —

The event ids happening in this time period.

lock()

Places an exclusive lock for a calendar or an event.


    public
                    lock(string $calendar[, string $event = null ]) : mixed

Parameters

$calendar : string: The id of the calendar to lock
$event : string = null: The uid for the event to lock

Return values

mixed —

A lock ID on success, false if:

The calendar is already locked
The event is already locked
A calendar lock was requested and an event is already locked in the calendar

lookupFreeBusy()

Attempt to lookup the free/busy information for the given email address.


    public
                    lookupFreeBusy(string $email[, bool $json = false ]) : mixed

Parameters

$email : string: The email to lookup free/busy information for.
$json : bool = false: Return the data in a simple json format. If false, returns the vCalander object.

Return values

mixed —

modified()

Returns the last modification timestamp for the given uid.


    public
                    modified(string $uid[, string $calendar = null ]) : int

Parameters

$uid : string: The uid to look for.
$calendar : string = null: The calendar to search in.

Return values

int —

The timestamp for the last modification of $uid.

move()

Move an event.


    public
                    move(string $uid, string $source, string $target) : mixed

Parameters

$uid : string: The event UID.
$source : string: The source calendar's id.
$target : string: The target calendar's id.

Return values

mixed —

path_delete()

Deletes a file from the Kronolith tree.


    public
                    path_delete(string $path) : mixed

Parameters

$path : string: The path to the file.

Return values

mixed —

put()

Saves a file into the Kronolith tree.


    public
                    put(string $path, string $content, string $content_type) : array<string|int, mixed>

Parameters

$path : string: The path where to PUT the file.
$content : string: The file content.
$content_type : string: The file's content type.

Return values

array<string|int, mixed> —

The event UIDs.

quickAdd()

Imports an event parsed from a string.


    public
                    quickAdd(string $text[, string $calendar = null ]) : array<string|int, mixed>

Parameters

$text : string: The text to parse into an event
$calendar : string = null: The calendar into which the event will be imported. If 'null', the user's default calendar will be used.

Return values

array<string|int, mixed> —

The UID of all events that were added.

replace()

Replaces the event identified by UID with the content represented in the specified contentType.


    public
                    replace(string $uid, mixed $content, string $contentType[, string $calendar = null ]) : mixed

Parameters

$uid : string: Idenfity the event to replace.
$content : mixed: The content of the event. String or Horde_Icalendar_Vevent
$contentType : string: What format is the data in? Currently supports: text/calendar text/x-vcalendar (Ignored if content is Horde_Icalendar_Vevent) activesync (Horde_ActiveSync_Message_Appointment)
$calendar : string = null: Ensure the event is replaced in the specified calendar. @since 4.2.0

Return values

mixed —

For EAS operations, an array of 'uid' and 'atchash' are returned. @since 4.3.0

searchTags()

SearchTags API: Returns an application-agnostic array (useful for when doing a tag search across multiple applications)


    public
                    searchTags(array<string|int, mixed> $names[, int $max = 10 ], int $from[, string $resource_type = '' ][, string $user = null ][, bool $raw = false ]) : array<string|int, mixed>

The 'raw' results array can be returned instead by setting $raw = true.

Parameters

$names : array<string|int, mixed>: An array of tag_names to search for.
$max : int = 10: The maximum number of resources to return.
$from : int: The number of the resource to start with.
$resource_type : string = '': The resource type [event, calendar, '']
$user : string = null: Restrict results to resources owned by $user.
$raw : bool = false: Return the raw data?

Return values

array<string|int, mixed> —

An array of results:

 'title'    - The title for this resource.
 'desc'     - A terse description of this resource.
 'view_url' - The URL to view this resource.
 'app'      - The Horde application this resource belongs to.

shareHelp()

Returns the share helper prefix


    public
                    shareHelp() : string

Return values

string —

sources()

Returns a list of available sources.


    public
                    sources([bool $writeable = false ][, bool $sync_only = false ]) : array<string|int, mixed>

Parameters

$writeable : bool = false: If true, limits to writeable sources.
$sync_only : bool = false: Only include syncable sources.

Return values

array<string|int, mixed> —

An array of the available sources. Keys are source IDs, values are source titles.

subscribe()

Subscribe to a calendar.


    public
                    subscribe(array<string|int, mixed> $calendar) : mixed

Parameters

$calendar : array<string|int, mixed>: Calendar description hash, with required 'type' parameter. Currently supports 'http' and 'webcal' for remote calendars.

Return values

mixed —

unlock()

Releases a lock.


    public
                    unlock(array<string|int, mixed> $calendar, array<string|int, mixed> $lockid) : mixed

Parameters

$calendar : array<string|int, mixed>: The event to lock.
$lockid : array<string|int, mixed>: The lock id to unlock.

Return values

mixed —

unsubscribe()

Unsubscribe from a calendar.


    public
                    unsubscribe(array<string|int, mixed> $calendar) : mixed

Parameters

$calendar : array<string|int, mixed>: Calendar description array, with required 'type' parameter. Currently supports 'http' and 'webcal' for remote calendars.

Return values

mixed —

updateAttendee()

Updates an attendee's response status for a specified event.


    public
                    updateAttendee(Horde_Icalendar_Vevent $response[, string $sender = null ]) : mixed

Parameters

$response : Horde_Icalendar_Vevent: A Horde_Icalendar_Vevent object, with a valid UID attribute that points to an existing event. This is typically the vEvent portion of an iTip meeting-request response, with the attendee's response in an ATTENDEE parameter.
$sender : string = null: The email address of the person initiating the update. Attendees are only updated if this address matches.

Return values

mixed —

updateCalendar()

Update an internal calendar's information.


    public
                    updateCalendar(string $id, array<string|int, mixed> $info) : mixed

Parameters

$id : string: The calendar id.
$info : array<string|int, mixed>: An array of calendar information. @see self::addCalendar()

Return values

mixed —

_addiCalEvent()

Imports a single vEvent part to storage.


    protected
                    _addiCalEvent(Horde_Icalendar_Vevent $content, Kronolith_Driver $driver[, bool $exception = false ]) : string

Parameters

$content : Horde_Icalendar_Vevent: The vEvent part
$driver : Kronolith_Driver: The kronolith driver
$exception : bool = false: Content represents an exception in a recurrence series.

Return values

string —

The new event's uid

Kronolith_Api extends Horde_Registry_Api in package Kronolith

Table of Contents

Properties

$_links

Methods

addCalendar()

Parameters

Tags

Return values

browse()

Parameters

Tags

Return values

checkLocks()

Parameters

Tags

Return values

delete()

Parameters

Tags

Return values

deleteCalendar()

Parameters

Return values

eventFromUID()

Parameters

Tags

Return values

export()

Parameters

Tags

Return values

exportCalendar()

Parameters

Tags

Return values

getActionTimestamp()

Parameters

Tags

Return values

getAttachment()

Parameters

Tags

Return values

getCalendar()

Parameters

Tags

Return values

getChanges()

Parameters

Tags

Return values

getChangesByModSeq()

Parameters

Tags

Return values

getDefaultShare()

Tags

Return values

getFbCalendars()

Return values

getFreeBusy()

Parameters

Tags

Return values

getHighestModSeq()

Parameters

Tags

Return values

import()

Parameters

Tags

Return values

listBy()

Parameters

Tags

Return values

listCalendars()

Parameters

Return values

Kronolith_Api extends Horde_Registry_Api
in package

Kronolith