DAViCal
CalDAVRequest Class Reference

Public Member Functions

 __construct ( $options=array())
 
 setPermissions ()
 
 IsLocked ()
 
 IsPublic ()
 
 dav_name ()
 
 GetDepthName ()
 
 DepthRegexTail ( $for_collection_report=false)
 
 GetLockRow ( $lock_token)
 
 ValidateLockToken ( $lock_token)
 
 GetLockDetails ( $lock_token)
 
 FailIfLocked ()
 
 CoerceContentType ()
 
 PreferMinimal ()
 
 IsCollection ()
 
 IsCalendar ()
 
 IsAddressBook ()
 
 IsPrincipal ()
 
 IsProxyRequest ()
 
 IsInfiniteDepth ()
 
 CollectionId ()
 
 BuildSupportedPrivileges (&$reply, $privs=null)
 
 AllowedTo ( $activity)
 
 Privileges ()
 
 CheckEtagMatch ( $exists, $dest_etag)
 
 HavePrivilegeTo ( $do_what)
 
 UnsupportedRequest ( $unsupported)
 
 NeedPrivilege ( $privileges, $href=null)
 
 PreconditionFailed ( $status, $precondition, $explanation='', $xmlns='DAV:')
 
 MalformedRequest ( $text='Bad request')
 
 XMLResponse ( $status, $xmltree)
 
 DoResponse ( $status, $message="", $content_type="text/plain; charset=\"utf-8\"")
 
 DoMetrics ($status, $response_size, $script_time, $flush_time)
 

Static Public Member Functions

static kill_on_exit ()
 

Public Attributes

 $options
 
 $raw_post
 
 $method
 
 $depth
 
 $principal
 
 $current_user_principal_xml
 
 $user_agent
 
 $collection_id
 
 $collection_path
 
 $collection_type
 
 $destination
 
 $supported_privileges
 
 $ticket
 

Protected Attributes

 $exists
 
 $privileges
 

Static Private Member Functions

static supportedPrivileges ()
 

Private Attributes

 $prefer
 

Detailed Description

Definition at line 30 of file CalDAVRequest.php.

Constructor & Destructor Documentation

◆ __construct()

CalDAVRequest::__construct (   $options = array())

Create a new CalDAVRequest object.

Our path is /<script name>/<user name>/<user controlled> if it ends in a trailing '/' then it is referring to a DAV 'collection' but otherwise it is referring to a DAV data item.

Permissions are controlled as follows:

  1. if there is no <user name> component, the request has read privileges
  2. if the requester is an admin, the request has read/write priviliges
  3. if there is a <user name> component which matches the logged on user then the request has read/write privileges
  4. otherwise we query the defined relationships between users and use the minimum privileges returned from that analysis.

Allow a request for .../calendar.ics to translate into the calendar URL

A variety of requests may set the "Depth" header to control recursion

Per rfc2518, section 9.2, 'Depth' might not always be present, and if it is not present then a reasonable request-type-dependent default should be chosen.

MOVE/COPY use a "Destination" header and (optionally) an "Overwrite" one.

LOCK things use an "If" header to hold the lock in some cases, and "Lock-token" in others

Check for an access ticket.

LOCK things use a "Timeout" header to set a series of reducing alternative values

RFC2518, 5.2: URL pointing to a collection SHOULD end in '/', and if it does not then we SHOULD return a Content-location header with the correction...

We therefore look for a collection which matches one of the following URLs:

  • The exact request.
  • If the exact request, doesn't end in '/', then the request URL with a '/' appended
  • The request URL truncated to the last '/' The collection URL for this request is therefore the longest row in the result, so we can "... ORDER BY LENGTH(dav_name) DESC LIMIT 1"
Todo:
we should deprecate this now that Evolution 2.27 can do scheduling extensions

Extract the user whom we are accessing

Evaluate our permissions for accessing the target

If the content we are receiving is XML then we parse it here. RFC2518 says we should reasonably expect to see either text/xml or application/xml

Look out for If-None-Match or If-Match headers

Definition at line 118 of file CalDAVRequest.php.

Member Function Documentation

◆ AllowedTo()

CalDAVRequest::AllowedTo (   $activity)

Are we allowed to do the requested activity

+---------—+---------------------------------------------------—+ | METHOD | PRIVILEGES | +---------—+---------------------------------------------------—+ | MKCALENDAR | DAV:bind | | REPORT | DAV:read or CALDAV:read-free-busy (on all referenced | | | resources) | +---------—+---------------------------------------------------—+

Parameters
string$activityThe activity we want to do.

Definition at line 965 of file CalDAVRequest.php.

◆ BuildSupportedPrivileges()

CalDAVRequest::BuildSupportedPrivileges ( $reply,
  $privs = null 
)

Returns the array of supported privileges converted into XMLElements

Definition at line 927 of file CalDAVRequest.php.

◆ CheckEtagMatch()

CalDAVRequest::CheckEtagMatch (   $exists,
  $dest_etag 
)

Check that the incoming Etag matches the one for the existing (or non-existing) resource.

Parameters
boolean$existsWhether the destination exists
string$dest_etagThe etag for the destination.

RFC2068, 14.25: If none of the entity tags match, or if "*" is given and no current entity exists, the server MUST NOT perform the requested method, and MUST return a 412 (Precondition Failed) response.

RFC2068, 14.25: If none of the entity tags match, or if "*" is given and no current entity exists, the server MUST NOT perform the requested method, and MUST return a 412 (Precondition Failed) response.

RFC2068, 14.26: If any of the entity tags match the entity tag of the entity that would have been returned in the response to a similar GET request (without the If-None-Match header) on that resource, or if "*" is given and any current entity exists for that resource, then the server MUST NOT perform the requested method.

Definition at line 1041 of file CalDAVRequest.php.

◆ CoerceContentType()

CalDAVRequest::CoerceContentType ( )

Coerces the Content-type of the request into something valid/appropriate

Todo:
: Perhaps we should look at the target collection type, also.

Null (or peculiar) content-type supplied so we have to try and work it out...

Definition at line 807 of file CalDAVRequest.php.

◆ CollectionId()

CalDAVRequest::CollectionId ( )

Returns the ID of the collection of, or containing this request

Definition at line 919 of file CalDAVRequest.php.

◆ dav_name()

CalDAVRequest::dav_name ( )

Returns the dav_name of the resource in our internal namespace

Definition at line 672 of file CalDAVRequest.php.

◆ DepthRegexTail()

CalDAVRequest::DepthRegexTail (   $for_collection_report = false)

Returns the tail of a Regex appropriate for this Depth, when appended to

Definition at line 690 of file CalDAVRequest.php.

◆ DoMetrics()

CalDAVRequest::DoMetrics (   $status,
  $response_size,
  $script_time,
  $flush_time 
)

Record the metrics related to this request.

Parameters
statusThe HTTP status code for this response
response_sizeThe size of the response (bytes).
script_timeThe time taken to generate the response (pre-sending)
flush_timeThe time taken to send the response (buffers flushed)

Definition at line 1272 of file CalDAVRequest.php.

◆ DoResponse()

CalDAVRequest::DoResponse (   $status,
  $message = "",
  $content_type = "text/plain; charset=\"utf-8\"" 
)

Utility function we call when we have a simple status-based response to return to the client. Possibly

Parameters
int$statusThe HTTP status code to send.
string$messageThe friendly text message to send with the response.

Definition at line 1200 of file CalDAVRequest.php.

◆ FailIfLocked()

CalDAVRequest::FailIfLocked ( )

This will either (a) return false if no locks apply, or (b) return the lock_token which the request successfully included to open the lock, or: (c) respond directly to the client with the failure.

Returns
mixed false (no lock) or opaquelocktoken (opened lock)

Already locked - deny it

Definition at line 772 of file CalDAVRequest.php.

◆ GetDepthName()

CalDAVRequest::GetDepthName ( )

Returns the name for this depth: 0, 1, infinity

Definition at line 681 of file CalDAVRequest.php.

◆ GetLockDetails()

CalDAVRequest::GetLockDetails (   $lock_token)

Returns the DB object associated with a lock token, or false.

Parameters
string$lock_tokenThe opaquelocktoken which we are looking for

Definition at line 758 of file CalDAVRequest.php.

◆ GetLockRow()

CalDAVRequest::GetLockRow (   $lock_token)

Returns the locked row, either from the cache or from the database

Parameters
string$dav_nameThe resource which we want to know the lock status for

Definition at line 702 of file CalDAVRequest.php.

◆ HavePrivilegeTo()

CalDAVRequest::HavePrivilegeTo (   $do_what)

Is the user has the privileges to do what is requested.

Definition at line 1092 of file CalDAVRequest.php.

◆ IsAddressBook()

CalDAVRequest::IsAddressBook ( )

Returns true if the URL referenced by this request points at an addressbook collection.

Definition at line 880 of file CalDAVRequest.php.

◆ IsCalendar()

CalDAVRequest::IsCalendar ( )

Returns true if the URL referenced by this request points at a calendar collection.

Definition at line 871 of file CalDAVRequest.php.

◆ IsCollection()

CalDAVRequest::IsCollection ( )

Returns true if the URL referenced by this request points at a collection.

Definition at line 860 of file CalDAVRequest.php.

◆ IsInfiniteDepth()

CalDAVRequest::IsInfiniteDepth ( )

Returns true if the request asked for infinite depth

Definition at line 911 of file CalDAVRequest.php.

◆ IsLocked()

CalDAVRequest::IsLocked ( )

Checks whether the resource is locked, returning any lock token, or false

Todo:
This logic does not catch all locking scenarios. For example an infinite depth request should check the permissions for all collections and resources within that. At present we only maintain permissions on a per-collection basis though.

Find the locks that might apply and load them into an array

Definition at line 593 of file CalDAVRequest.php.

◆ IsPrincipal()

CalDAVRequest::IsPrincipal ( )

Returns true if the URL referenced by this request points at a principal.

Definition at line 889 of file CalDAVRequest.php.

◆ IsProxyRequest()

CalDAVRequest::IsProxyRequest ( )

Returns true if the URL referenced by this request is within a proxy URL

Definition at line 900 of file CalDAVRequest.php.

◆ IsPublic()

CalDAVRequest::IsPublic ( )

Checks whether the collection is public

Definition at line 630 of file CalDAVRequest.php.

◆ MalformedRequest()

CalDAVRequest::MalformedRequest (   $text = 'Bad request')

Send a simple error informing the client that was a malformed request

Parameters
string$textAn optional text description of the failure.

Definition at line 1169 of file CalDAVRequest.php.

◆ NeedPrivilege()

CalDAVRequest::NeedPrivilege (   $privileges,
  $href = null 
)

Send a need-privileges error response. This function will only return if the $href is not supplied and the current user has the specified permission for the request path.

Parameters
string$privilegeThe name of the needed privilege.
string$hrefThe unconstructed URI where we needed the privilege.

Definition at line 1128 of file CalDAVRequest.php.

◆ PreconditionFailed()

CalDAVRequest::PreconditionFailed (   $status,
  $precondition,
  $explanation = '',
  $xmlns = 'DAV:' 
)

Send an error response for a failed precondition.

Parameters
int$statusThe status code for the failed precondition. Normally 403
string$preconditionThe namespaced precondition tag.
string$explanationAn optional text explanation for the failure.

Definition at line 1153 of file CalDAVRequest.php.

◆ PreferMinimal()

CalDAVRequest::PreferMinimal ( )

Returns true if the 'Prefer: return=minimal' or 'Brief: t' were present in the request headers.

Definition at line 848 of file CalDAVRequest.php.

◆ Privileges()

CalDAVRequest::Privileges ( )

Return the privileges bits for the current session user to this resource

Definition at line 1030 of file CalDAVRequest.php.

◆ setPermissions()

CalDAVRequest::setPermissions ( )

Permissions are controlled as follows:

  1. if the path is '/', the request has read privileges
  2. if the requester is an admin, the request has read/write priviliges
  3. if there is a <user name> component which matches the logged on user then the request has read/write privileges
  4. otherwise we query the defined relationships between users and use the minimum privileges returned from that analysis.
Parameters
int$user_noThe current user number

In other cases we need to query the database for permissions

convert privileges into older style permissions

Definition at line 525 of file CalDAVRequest.php.

◆ UnsupportedRequest()

CalDAVRequest::UnsupportedRequest (   $unsupported)

Sometimes it's a perfectly formed request, but we just don't do that :-(

Parameters
array$unsupportedAn array of the properties we don't support.

Definition at line 1105 of file CalDAVRequest.php.

◆ ValidateLockToken()

CalDAVRequest::ValidateLockToken (   $lock_token)

Checks to see whether the lock token given matches one of the ones handed in with the request.

Parameters
string$lock_tokenThe opaquelocktoken which we are looking for

Definition at line 727 of file CalDAVRequest.php.

◆ XMLResponse()

CalDAVRequest::XMLResponse (   $status,
  $xmltree 
)

Send an XML Response. This function will never return.

Parameters
int$statusThe HTTP status to respond
XMLElement$xmltreeAn XMLElement tree to be rendered

Definition at line 1181 of file CalDAVRequest.php.

Member Data Documentation

◆ $collection_id

CalDAVRequest::$collection_id

The ID of the collection containing this path, or of this path if it is a collection

Definition at line 70 of file CalDAVRequest.php.

◆ $collection_path

CalDAVRequest::$collection_path

The path corresponding to the collection_id

Definition at line 75 of file CalDAVRequest.php.

◆ $collection_type

CalDAVRequest::$collection_type

The type of collection being requested: calendar, schedule-inbox, schedule-outbox

Definition at line 81 of file CalDAVRequest.php.

◆ $current_user_principal_xml

CalDAVRequest::$current_user_principal_xml

The 'current_user_principal_xml' the DAV:current-user-principal answer. An XMLElement object with an <href> or <unauthenticated> fragment.

Definition at line 60 of file CalDAVRequest.php.

◆ $depth

CalDAVRequest::$depth

The depth parameter from the request headers, coerced into a valid integer: 0, 1 or DEPTH_INFINITY which is defined above. The default is set per various RFCs.

Definition at line 48 of file CalDAVRequest.php.

◆ $destination

CalDAVRequest::$destination

The value of any 'Destionation:' header, if present.

Definition at line 92 of file CalDAVRequest.php.

◆ $exists

CalDAVRequest::$exists
protected

The type of collection being requested: calendar, schedule-inbox, schedule-outbox

Definition at line 87 of file CalDAVRequest.php.

◆ $method

CalDAVRequest::$method

The HTTP request method: PROPFIND, LOCK, REPORT, OPTIONS, etc...

Definition at line 42 of file CalDAVRequest.php.

◆ $prefer

CalDAVRequest::$prefer
private

An array of values from the 'Prefer' header. At present only 'return=minimal' is acted on in any way - you can test that value with the PreferMinimal() method.

Definition at line 113 of file CalDAVRequest.php.

◆ $privileges

CalDAVRequest::$privileges
protected

The decimal privileges allowed by this user to the identified resource.

Definition at line 97 of file CalDAVRequest.php.

◆ $raw_post

CalDAVRequest::$raw_post

The raw data sent along with the request

Definition at line 37 of file CalDAVRequest.php.

◆ $supported_privileges

CalDAVRequest::$supported_privileges

A static structure of supported privileges.

Definition at line 102 of file CalDAVRequest.php.

◆ $ticket

CalDAVRequest::$ticket

A DAVTicket object, if there is a ?ticket=id or Ticket: id with this request

Definition at line 107 of file CalDAVRequest.php.

◆ $user_agent

CalDAVRequest::$user_agent

The user agent making the request.

Definition at line 65 of file CalDAVRequest.php.


The documentation for this class was generated from the following file: