1<?php
2/**
3 * Copyright 2004-2017 Horde LLC (http://www.horde.org/)
4 *
5 * See the enclosed file COPYING for license information (LGPL). If you
6 * did not receive this file, see http://www.horde.org/licenses/lgpl21.
7 *
8 * @category Kolab
9 * @package  Kolab_Storage
10 * @author   Gunnar Wrobel <wrobel@pardus.de>
11 * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
12 */
13
14/**
15 * The Horde_Kolab_Storage class provides the means to access the
16 * Kolab server storage for groupware objects.
17 *
18 * To get access to the folder handling you would do the following:
19 *
20 *   <code>
21 *     require_once 'Horde/Kolab/Storage.php';
22 *     $folder = Horde_Kolab_Storage::getFolder('INBOX/Calendar');
23 *   </code>
24 *
25 *  or (in case you are dealing with share identifications):
26 *
27 *   <code>
28 *     require_once 'Horde/Kolab/Storage.php';
29 *     $folder = Horde_Kolab_Storage::getShare(Auth::getAuth(), 'event');
30 *   </code>
31 *
32 * To access data in a share (or folder) you need to retrieve the
33 * corresponding data object:
34 *
35 *   <code>
36 *     require_once 'Horde/Kolab/Storage.php';
37 *     $folder = Horde_Kolab_Storage::getShareData(Auth::getAuth(), 'event');
38 *   </code>
39 *
40 * @category Kolab
41 * @package  Kolab_Storage
42 * @author   Gunnar Wrobel <wrobel@pardus.de>
43 * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
44 */
45interface Horde_Kolab_Storage
46{
47    /** The package version */
48    const VERSION = '2.2.4';
49
50    /**
51     * Get the folder list object.
52     *
53     * @return Horde_Kolab_Storage_List_Tools  The handler for the list of
54     *                                         folders present in the Kolab
55     *                                         backend.
56     */
57    public function getList();
58
59    /**
60     * Get a folder list object for a "system" user.
61     *
62     * @param string $type The type of system user.
63     *
64     * @return Horde_Kolab_Storage_List_Tools  The handler for the list of
65     *                                         folders present in the Kolab
66     *                                         backend.
67     */
68    public function getSystemList($type);
69
70    /**
71     * Get a folder representation.
72     *
73     * @param string $folder The folder name.
74     *
75     * @return Horde_Kolab_Storage_Folder The Kolab folder object.
76     */
77    public function getFolder($folder);
78
79    /**
80     * Return a data handler for accessing data in the specified
81     * folder.
82     *
83     * @param string $folder       The name of the folder.
84     * @param string $object_type  The type of data we want to
85     *                             access in the folder.
86     * @param int    $data_version Format version of the object data.
87     *
88     * @return Horde_Kolab_Storage_Data The data object.
89     */
90    public function getData($folder, $object_type = null, $data_version = 1);
91}
92
93