Plugin
extends ServerPlugin
in package
CalDAV scheduling plugin.
=========================.
This plugin provides the functionality added by the "Scheduling Extensions to CalDAV" standard, as defined in RFC6638.
calendar-auto-schedule largely works by intercepting a users request to update their local calendar. If a user creates a new event with attendees, this plugin is supposed to grab the information from that event, and notify the attendees of this.
There's 3 possible transports for this:
- local delivery
- delivery through email (iMip)
- server-to-server delivery (iSchedule)
iMip is simply, because we just need to add the iTip message as an email attachment. Local delivery is harder, because we both need to add this same message to a local DAV inbox, as well as live-update the relevant events.
iSchedule is something for later.
Tags
Table of Contents
- NS_CALDAV = 'urn:ietf:params:xml:ns:caldav'
- This is the official CalDAV namespace.
- $server : Server
- Reference to main Server object.
- beforeUnbind() : mixed
- This method is triggered before a file gets deleted.
- calendarObjectChange() : mixed
- This method is triggered whenever there was a calendar object gets created or updated.
- deliver() : mixed
- This method is responsible for delivering the ITip message.
- getFeatures() : array<string|int, mixed>
- Returns a list of features for the DAV: HTTP header.
- getHTTPMethods() : array<string|int, mixed>
- Use this method to tell the server this plugin defines additional HTTP methods.
- getPluginInfo() : array<string|int, mixed>
- Returns a bunch of meta-data about the plugin.
- getPluginName() : string
- Returns the name of the plugin.
- getSupportedPrivilegeSet() : mixed
- This method is triggered whenever a subsystem requests the privileges that are supported on a particular node.
- getSupportedReportSet() : array<string|int, mixed>
- Returns a list of reports this plugin supports.
- httpPost() : bool
- This method handles POST request for the outbox.
- initialize() : mixed
- Initializes the plugin.
- outboxRequest() : mixed
- This method handles POST requests to the schedule-outbox.
- propFind() : mixed
- This method handler is invoked during fetching of properties.
- propPatch() : mixed
- This method is called during property updates.
- scheduleLocalDelivery() : mixed
- Event handler for the 'schedule' event.
- getAddressesForPrincipal() : array<string|int, mixed>
- Returns a list of addresses that are associated with a principal.
- getFreeBusyForEmail() : array<string|int, mixed>
- Returns free-busy information for a specific address. The returned data is an array containing the following properties:.
- handleFreeBusyRequest() : string
- This method is responsible for parsing a free-busy query request and returning it's result.
- processICalendarChange() : mixed
- This method looks at an old iCalendar object, a new iCalendar object and starts sending scheduling messages based on the changes.
- scheduleReply() : bool
- This method checks the 'Schedule-Reply' header and returns false if it's 'F', otherwise true.
Constants
NS_CALDAV
This is the official CalDAV namespace.
public
mixed
NS_CALDAV
= 'urn:ietf:params:xml:ns:caldav'
Properties
$server
Reference to main Server object.
protected
Server
$server
Methods
beforeUnbind()
This method is triggered before a file gets deleted.
public
beforeUnbind(string $path) : mixed
We use this event to make sure that when this happens, attendees get cancellations, and organizers get 'DECLINED' statuses.
Parameters
- $path : string
Return values
mixed —calendarObjectChange()
This method is triggered whenever there was a calendar object gets created or updated.
public
calendarObjectChange(RequestInterface $request, ResponseInterface $response, VCalendar $vCal, mixed $calendarPath, mixed &$modified, mixed $isNew) : mixed
Parameters
- $request : RequestInterface
-
HTTP request
- $response : ResponseInterface
-
HTTP Response
- $vCal : VCalendar
-
Parsed iCalendar object
- $calendarPath : mixed
-
Path to calendar collection
- $modified : mixed
-
the iCalendar object has been touched
- $isNew : mixed
-
Whether this was a new item or we're updating one
Return values
mixed —deliver()
This method is responsible for delivering the ITip message.
public
deliver(Message $iTipMessage) : mixed
Parameters
- $iTipMessage : Message
Return values
mixed —getFeatures()
Returns a list of features for the DAV: HTTP header.
public
getFeatures() : array<string|int, mixed>
Return values
array<string|int, mixed> —getHTTPMethods()
Use this method to tell the server this plugin defines additional HTTP methods.
public
getHTTPMethods(string $uri) : array<string|int, mixed>
This method is passed a uri. It should only return HTTP methods that are available for the specified uri.
Parameters
- $uri : string
Return values
array<string|int, mixed> —getPluginInfo()
Returns a bunch of meta-data about the plugin.
public
getPluginInfo() : array<string|int, mixed>
Providing this information is optional, and is mainly displayed by the Browser plugin.
The description key in the returned array may contain html and will not be sanitized.
Return values
array<string|int, mixed> —getPluginName()
Returns the name of the plugin.
public
getPluginName() : string
Using this name other plugins will be able to access other plugins using Server::getPlugin
Return values
string —getSupportedPrivilegeSet()
This method is triggered whenever a subsystem requests the privileges that are supported on a particular node.
public
getSupportedPrivilegeSet(INode $node, array<string|int, mixed> &$supportedPrivilegeSet) : mixed
We need to add a number of privileges for scheduling purposes.
Parameters
- $node : INode
- $supportedPrivilegeSet : array<string|int, mixed>
Return values
mixed —getSupportedReportSet()
Returns a list of reports this plugin supports.
public
getSupportedReportSet(string $uri) : array<string|int, mixed>
This will be used in the {DAV:}supported-report-set property. Note that you still need to subscribe to the 'report' event to actually implement them
Parameters
- $uri : string
Return values
array<string|int, mixed> —httpPost()
This method handles POST request for the outbox.
public
httpPost(RequestInterface $request, ResponseInterface $response) : bool
Parameters
- $request : RequestInterface
- $response : ResponseInterface
Return values
bool —initialize()
Initializes the plugin.
public
initialize(Server $server) : mixed
Parameters
- $server : Server
Return values
mixed —outboxRequest()
This method handles POST requests to the schedule-outbox.
public
outboxRequest(IOutbox $outboxNode, RequestInterface $request, ResponseInterface $response) : mixed
Currently, two types of requests are supported:
- FREEBUSY requests from RFC 6638
- Simple iTIP messages from draft-desruisseaux-caldav-sched-04
The latter is from an expired early draft of the CalDAV scheduling extensions, but iCal depends on a feature from that spec, so we implement it.
Parameters
- $outboxNode : IOutbox
- $request : RequestInterface
- $response : ResponseInterface
Return values
mixed —propFind()
This method handler is invoked during fetching of properties.
public
propFind(PropFind $propFind, INode $node) : mixed
We use this event to add calendar-auto-schedule-specific properties.
Parameters
Return values
mixed —propPatch()
This method is called during property updates.
public
propPatch(string $path, PropPatch $propPatch) : mixed
Parameters
- $path : string
- $propPatch : PropPatch
Return values
mixed —scheduleLocalDelivery()
Event handler for the 'schedule' event.
public
scheduleLocalDelivery(Message $iTipMessage) : mixed
This handler attempts to look at local accounts to deliver the scheduling object.
Parameters
- $iTipMessage : Message
Return values
mixed —getAddressesForPrincipal()
Returns a list of addresses that are associated with a principal.
protected
getAddressesForPrincipal(string $principal) : array<string|int, mixed>
Parameters
- $principal : string
Return values
array<string|int, mixed> —getFreeBusyForEmail()
Returns free-busy information for a specific address. The returned data is an array containing the following properties:.
protected
getFreeBusyForEmail(string $email, DateTimeInterface $start, DateTimeInterface $end, Component $request) : array<string|int, mixed>
calendar-data : A VFREEBUSY VObject request-status : an iTip status code. href: The principal's email address, as requested
The following request status codes may be returned:
- 2.0;description
- 3.7;description
Parameters
- $email : string
-
address
- $start : DateTimeInterface
- $end : DateTimeInterface
- $request : Component
Return values
array<string|int, mixed> —handleFreeBusyRequest()
This method is responsible for parsing a free-busy query request and returning it's result.
protected
handleFreeBusyRequest(IOutbox $outbox, Component $vObject, RequestInterface $request, ResponseInterface $response) : string
Parameters
- $outbox : IOutbox
- $vObject : Component
- $request : RequestInterface
- $response : ResponseInterface
Return values
string —processICalendarChange()
This method looks at an old iCalendar object, a new iCalendar object and starts sending scheduling messages based on the changes.
protected
processICalendarChange([VCalendar|string $oldObject = null ], VCalendar $newObject, array<string|int, mixed> $addresses[, array<string|int, mixed> $ignore = [] ][, bool &$modified = false ]) : mixed
A list of addresses needs to be specified, so the system knows who made the update, because the behavior may be different based on if it's an attendee or an organizer.
This method may update $newObject to add any status changes.
Parameters
- $oldObject : VCalendar|string = null
- $newObject : VCalendar
- $addresses : array<string|int, mixed>
- $ignore : array<string|int, mixed> = []
-
any addresses to not send messages to
- $modified : bool = false
-
a marker to indicate that the original object modified by this process
Return values
mixed —scheduleReply()
This method checks the 'Schedule-Reply' header and returns false if it's 'F', otherwise true.
private
scheduleReply(RequestInterface $request) : bool
Parameters
- $request : RequestInterface