1: <?php
  2: /**
  3:  * A library for accessing the Kolab user database.
  4:  *
  5:  * PHP version 5
  6:  *
  7:  * @category Kolab
  8:  * @package  Kolab_Server
  9:  * @author   Gunnar Wrobel <wrobel@pardus.de>
 10:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 11:  * @link     http://pear.horde.org/index.php?package=Kolab_Server
 12:  */
 13: 
 14: /**
 15:  * This class defines the interface of a generic Kolab user database.
 16:  *
 17:  * Copyright 2008-2012 Horde LLC (http://www.horde.org/)
 18:  *
 19:  * See the enclosed file COPYING for license information (LGPL). If you
 20:  * did not receive this file, see http://www.horde.org/licenses/lgpl21.
 21:  *
 22:  * @category Kolab
 23:  * @package  Kolab_Server
 24:  * @author   Gunnar Wrobel <wrobel@pardus.de>
 25:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 26:  * @link     http://pear.horde.org/index.php?package=Kolab_Server
 27:  */
 28: interface Horde_Kolab_Server_Interface
 29: {
 30:     /**
 31:      * Connect to the server.
 32:      *
 33:      * @param string $guid The global unique id of the user.
 34:      * @param string $pass The password.
 35:      *
 36:      * @return NULL.
 37:      *
 38:      * @throws Horde_Kolab_Server_Exception If the connection failed.
 39:      */
 40:     public function connectGuid($guid = '', $pass = '');
 41: 
 42:     /**
 43:      * Get the current GUID
 44:      *
 45:      * @return string The GUID of the currently connected user.
 46:      */
 47:     public function getGuid();
 48: 
 49:     /**
 50:      * Get the base GUID of this server
 51:      *
 52:      * @return string The base GUID of this server.
 53:      */
 54:     public function getBaseGuid();
 55: 
 56:     /**
 57:      * Low level access to reading object data.
 58:      *
 59:      * This function provides direct access to the Server data.
 60:      *
 61:      * Usually you should use
 62:      *
 63:      * <code>
 64:      *   $object = $server->fetch('a server uid');
 65:      *   $variable = $object['attribute']
 66:      * </code>
 67:      *
 68:      * to access object attributes. This is slower but takes special object
 69:      * handling into account (e.g. custom attribute parsing).
 70:      *
 71:      * @param string $guid The object to retrieve.
 72:      *
 73:      * @return array An array of attributes.
 74:      *
 75:      * @throws Horde_Kolab_Server_Exception
 76:      */
 77:     public function read($guid);
 78: 
 79:     /**
 80:      * Low level access to reading some object attributes.
 81:      *
 82:      * @param string $guid  The object to retrieve.
 83:      * @param string $attrs Restrict to these attributes.
 84:      *
 85:      * @return array An array of attributes.
 86:      *
 87:      * @throws Horde_Kolab_Server_Exception
 88:      *
 89:      * @see Horde_Kolab_Server::read
 90:      */
 91:     public function readAttributes($guid, array $attrs);
 92: 
 93:     /**
 94:      * Finds object data matching a given set of criteria.
 95:      *
 96:      * @param string $query  The LDAP search query
 97:      * @param array  $params Additional search parameters.
 98:      *
 99:      * @return Horde_Kolab_Server_Result The result object.
100:      *
101:      * @throws Horde_Kolab_Server_Exception
102:      */
103:     public function find($query, array $params = array());
104: 
105:     /**
106:      * Finds all object data below a parent matching a given set of criteria.
107:      *
108:      * @param string $query  The LDAP search query
109:      * @param string $parent The parent to search below.
110:      * @param array  $params Additional search parameters.
111:      *
112:      * @return Horde_Kolab_Server_Result The result object.
113:      *
114:      * @throws Horde_Kolab_Server_Exception
115:      */
116:     public function findBelow($query, $parent, array $params = array());
117: 
118:     /**
119:      * Modify existing object data.
120:      *
121:      * @param Horde_Kolab_Server_Object $object The object to be modified.
122:      * @param array                     $data   The attributes of the object
123:      *                                          to be stored.
124:      *
125:      * @return NULL
126:      *
127:      * @throws Horde_Kolab_Server_Exception
128:      */
129:     public function save(
130:         Horde_Kolab_Server_Object_Interface $object,
131:         array $data
132:     );
133: 
134:     /**
135:      * Add new object data.
136:      *
137:      * @param Horde_Kolab_Server_Object $object The object to be added.
138:      * @param array                     $data   The attributes of the object
139:      *                                          to be added.
140:      *
141:      * @return NULL
142:      *
143:      * @throws Horde_Kolab_Server_Exception
144:      */
145:     public function add(
146:         Horde_Kolab_Server_Object_Interface $object,
147:         array $data
148:     );
149: 
150:     /**
151:      * Delete an object.
152:      *
153:      * @param string $guid The GUID of the object to be deleted.
154:      *
155:      * @return NULL
156:      *
157:      * @throws Horde_Kolab_Server_Exception
158:      */
159:     public function delete($guid);
160: 
161:     /**
162:      * Rename an object.
163:      *
164:      * @param string $guid The GUID of the object to be renamed.
165:      * @param string $new  The new GUID of the object.
166:      *
167:      * @return NULL
168:      *
169:      * @throws Horde_Kolab_Server_Exception
170:      */
171:     public function rename($guid, $new);
172: 
173:     /**
174:      * Return the database schema description.
175:      *
176:      * @return array The schema.
177:      *
178:      * @throws Horde_Kolab_Server_Exception If retrieval of the schema failed.
179:      */
180:     public function getSchema();
181: 
182:     /**
183:      * Get the parent GUID of this object.
184:      *
185:      * @param string $guid The GUID of the child.
186:      *
187:      * @return string the parent GUID of this object.
188:      */
189:     public function getParentGuid($guid);
190: }