1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<?php
/**
* @copyright Copyright (c) 2016, ownCloud, Inc.
*
* @author Bart Visscher <bartv@thisnet.nl>
* @author Morris Jobke <hey@morrisjobke.de>
* @author Robin McCorkell <robin@mccorkell.me.uk>
* @author Thomas Müller <thomas.mueller@tmit.eu>
*
* @license AGPL-3.0
*
* This code is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License, version 3,
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License, version 3,
* along with this program. If not, see <http://www.gnu.org/licenses/>
*
*/
/**
* Public interface of ownCloud for apps to use.
* Contacts Class
*
*/
// use OCP namespace for all classes that are considered public.
// This means that they should be used by apps instead of the internal ownCloud classes
namespace OCP {
/**
* This class provides access to the contacts app. Use this class exclusively if you want to access contacts.
*
* Contacts in general will be expressed as an array of key-value-pairs.
* The keys will match the property names defined in https://tools.ietf.org/html/rfc2426#section-1
*
* Proposed workflow for working with contacts:
* - search for the contacts
* - manipulate the results array
* - createOrUpdate will save the given contacts overwriting the existing data
*
* For updating it is mandatory to keep the id.
* Without an id a new contact will be created.
*
* @deprecated 8.1.0 use methods of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
class Contacts {
/**
* This function is used to search and find contacts within the users address books.
* In case $pattern is empty all contacts will be returned.
*
* Example:
* Following function shows how to search for contacts for the name and the email address.
*
* public static function getMatchingRecipient($term) {
* // The API is not active -> nothing to do
* if (!\OCP\Contacts::isEnabled()) {
* return array();
* }
*
* $result = \OCP\Contacts::search($term, array('FN', 'EMAIL'));
* $receivers = array();
* foreach ($result as $r) {
* $id = $r['id'];
* $fn = $r['FN'];
* $email = $r['EMAIL'];
* if (!is_array($email)) {
* $email = array($email);
* }
*
* // loop through all email addresses of this contact
* foreach ($email as $e) {
* $displayName = $fn . " <$e>";
* $receivers[] = array(
* 'id' => $id,
* 'label' => $displayName,
* 'value' => $displayName);
* }
* }
*
* return $receivers;
* }
*
*
* @param string $pattern which should match within the $searchProperties
* @param array $searchProperties defines the properties within the query pattern should match
* @param array $options - for future use. One should always have options!
* @return array an array of contacts which are arrays of key-value-pairs
* @deprecated 8.1.0 use search() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function search($pattern, $searchProperties = array(), $options = array()) {
$cm = \OC::$server->getContactsManager();
return $cm->search($pattern, $searchProperties, $options);
}
/**
* This function can be used to delete the contact identified by the given id
*
* @param object $id the unique identifier to a contact
* @param string $address_book_key
* @return bool successful or not
* @deprecated 8.1.0 use delete() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function delete($id, $address_book_key) {
$cm = \OC::$server->getContactsManager();
return $cm->delete($id, $address_book_key);
}
/**
* This function is used to create a new contact if 'id' is not given or not present.
* Otherwise the contact will be updated by replacing the entire data set.
*
* @param array $properties this array if key-value-pairs defines a contact
* @param string $address_book_key identifier of the address book in which the contact shall be created or updated
* @return array an array representing the contact just created or updated
* @deprecated 8.1.0 use createOrUpdate() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function createOrUpdate($properties, $address_book_key) {
$cm = \OC::$server->getContactsManager();
return $cm->createOrUpdate($properties, $address_book_key);
}
/**
* Check if contacts are available (e.g. contacts app enabled)
*
* @return bool true if enabled, false if not
* @deprecated 8.1.0 use isEnabled() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function isEnabled() {
$cm = \OC::$server->getContactsManager();
return $cm->isEnabled();
}
/**
* @param \OCP\IAddressBook $address_book
* @deprecated 8.1.0 use registerAddressBook() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function registerAddressBook(\OCP\IAddressBook $address_book) {
$cm = \OC::$server->getContactsManager();
$cm->registerAddressBook($address_book);
}
/**
* @param \OCP\IAddressBook $address_book
* @deprecated 8.1.0 use unregisterAddressBook() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function unregisterAddressBook(\OCP\IAddressBook $address_book) {
$cm = \OC::$server->getContactsManager();
$cm->unregisterAddressBook($address_book);
}
/**
* @return array
* @deprecated 8.1.0 use getAddressBooks() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function getAddressBooks() {
$cm = \OC::$server->getContactsManager();
return $cm->getAddressBooks();
}
/**
* removes all registered address book instances
* @deprecated 8.1.0 use clear() of \OCP\Contacts\IManager - \OC::$server->getContactsManager();
* @since 5.0.0
*/
public static function clear() {
$cm = \OC::$server->getContactsManager();
$cm->clear();
}
}
}
|
