dav/SabreDAV/lib/Sabre/DAVACL/IPrincipalBackend.php

   1 <?php
   2
   3 /**
   4  * Implement this interface to create your own principal backends.
   5  *
   6  * Creating backends for principals is entirely optional. You can also
   7  * implement Sabre_DAVACL_IPrincipal directly. This interface is used solely by
   8  * Sabre_DAVACL_AbstractPrincipalCollection.
   9  *
  10  * @package Sabre
  11  * @subpackage DAVACL
  12  * @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved.
  13  * @author Evert Pot (http://www.rooftopsolutions.nl/)
  14  * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
  15  */
  16 interface Sabre_DAVACL_IPrincipalBackend {
  17
  18     /**
  19      * Returns a list of principals based on a prefix.
  20      *
  21      * This prefix will often contain something like 'principals'. You are only
  22      * expected to return principals that are in this base path.
  23      *
  24      * You are expected to return at least a 'uri' for every user, you can
  25      * return any additional properties if you wish so. Common properties are:
  26      *   {DAV:}displayname
  27      *   {http://sabredav.org/ns}email-address - This is a custom SabreDAV
  28      *     field that's actually injected in a number of other properties. If
  29      *     you have an email address, use this property.
  30      *
  31      * @param string $prefixPath
  32      * @return array
  33      */
  34     function getPrincipalsByPrefix($prefixPath);
  35
  36     /**
  37      * Returns a specific principal, specified by it's path.
  38      * The returned structure should be the exact same as from
  39      * getPrincipalsByPrefix.
  40      *
  41      * @param string $path
  42      * @return array
  43      */
  44     function getPrincipalByPath($path);
  45
  46     /**
  47      * Updates one ore more webdav properties on a principal.
  48      *
  49      * The list of mutations is supplied as an array. Each key in the array is
  50      * a propertyname, such as {DAV:}displayname.
  51      *
  52      * Each value is the actual value to be updated. If a value is null, it
  53      * must be deleted.
  54      *
  55      * This method should be atomic. It must either completely succeed, or
  56      * completely fail. Success and failure can simply be returned as 'true' or
  57      * 'false'.
  58      *
  59      * It is also possible to return detailed failure information. In that case
  60      * an array such as this should be returned:
  61      *
  62      * array(
  63      *   200 => array(
  64      *      '{DAV:}prop1' => null,
  65      *   ),
  66      *   201 => array(
  67      *      '{DAV:}prop2' => null,
  68      *   ),
  69      *   403 => array(
  70      *      '{DAV:}prop3' => null,
  71      *   ),
  72      *   424 => array(
  73      *      '{DAV:}prop4' => null,
  74      *   ),
  75      * );
  76      *
  77      * In this previous example prop1 was successfully updated or deleted, and
  78      * prop2 was succesfully created.
  79      *
  80      * prop3 failed to update due to '403 Forbidden' and because of this prop4
  81      * also could not be updated with '424 Failed dependency'.
  82      *
  83      * This last example was actually incorrect. While 200 and 201 could appear
  84      * in 1 response, if there's any error (403) the other properties should
  85      * always fail with 423 (failed dependency).
  86      *
  87      * But anyway, if you don't want to scratch your head over this, just
  88      * return true or false.
  89      *
  90      * @param string $path
  91      * @param array $mutations
  92      * @return array|bool
  93      */
  94     function updatePrincipal($path, $mutations);
  95
  96     /**
  97      * This method is used to search for principals matching a set of
  98      * properties.
  99      *
 100      * This search is specifically used by RFC3744's principal-property-search
 101      * REPORT. You should at least allow searching on
 102      * http://sabredav.org/ns}email-address.
 103      *
 104      * The actual search should be a unicode-non-case-sensitive search. The
 105      * keys in searchProperties are the WebDAV property names, while the values
 106      * are the property values to search on.
 107      *
 108      * If multiple properties are being searched on, the search should be
 109      * AND'ed.
 110      *
 111      * This method should simply return an array with full principal uri's.
 112      *
 113      * If somebody attempted to search on a property the backend does not
 114      * support, you should simply return 0 results.
 115      *
 116      * You can also just return 0 results if you choose to not support
 117      * searching at all, but keep in mind that this may stop certain features
 118      * from working.
 119      *
 120      * @param string $prefixPath
 121      * @param array $searchProperties
 122      * @return array
 123      */
 124     function searchPrincipals($prefixPath, array $searchProperties);
 125
 126     /**
 127      * Returns the list of members for a group-principal
 128      *
 129      * @param string $principal
 130      * @return array
 131      */
 132     function getGroupMemberSet($principal);
 133
 134     /**
 135      * Returns the list of groups a principal is a member of
 136      *
 137      * @param string $principal
 138      * @return array
 139      */
 140     function getGroupMembership($principal);
 141
 142     /**
 143      * Updates the list of group members for a group principal.
 144      *
 145      * The principals should be passed as a list of uri's.
 146      *
 147      * @param string $principal
 148      * @param array $members
 149      * @return void
 150      */
 151     function setGroupMemberSet($principal, array $members);
 152
 153 }