1: <?php
2: /**
3: * IMP external API interface.
4: *
5: * This file defines IMP's external API interface. Other applications
6: * can interact with IMP through this API.
7: *
8: * Copyright 2009-2012 Horde LLC (http://www.horde.org/)
9: *
10: * See the enclosed file COPYING for license information (GPL). If you
11: * did not receive this file, see http://www.horde.org/licenses/gpl.
12: *
13: * @author Michael Slusarz <slusarz@horde.org>
14: * @category Horde
15: * @license http://www.horde.org/licenses/gpl GPL
16: * @package IMP
17: */
18: class IMP_Api extends Horde_Registry_Api
19: {
20: /**
21: * The listing of API calls that do not require permissions checking.
22: *
23: * @var array
24: */
25: public $noPerms = array(
26: 'compose', 'batchCompose'
27: );
28:
29: /**
30: * Returns a compose window link.
31: *
32: * @param string|array $args List of arguments to pass to compose.php.
33: * If this is passed in as a string, it will be
34: * parsed as a
35: * toaddress?subject=foo&cc=ccaddress
36: * (mailto-style) string.
37: * @param array $extra Hash of extra, non-standard arguments to
38: * pass to compose.php.
39: *
40: * @return Horde_Url The link to the message composition screen.
41: */
42: public function compose($args = array(), $extra = array())
43: {
44: $link = $this->batchCompose(array($args), array($extra));
45: return $link[0];
46: }
47:
48: /**
49: * Return a list of compose window links.
50: *
51: * @param string|array $args List of arguments to pass to compose.php.
52: * If this is passed in as a string, it will be
53: * parsed as a
54: * toaddress?subject=foo&cc=ccaddress
55: * (mailto-style) string.
56: * @param array $extra List of hashes of extra, non-standard
57: * arguments to pass to compose.php.
58: *
59: * @return array The list of Horde_Url objects with links to the message
60: * composition screen.
61: */
62: public function batchCompose($args = array(), $extra = array())
63: {
64: $links = array();
65: foreach ($args as $i => $arg) {
66: $links[$i] = IMP::composeLink($arg, !empty($extra[$i]) ? $extra[$i] : array());
67: }
68: return $links;
69: }
70:
71: /**
72: * Returns the list of folders.
73: *
74: * @return array The list of IMAP folders. Keys are the IMAP mailbox
75: * name (UTF7-IMAP). Values have the following keys:
76: * - label: (string) Human readable label.
77: * - level: (integer) The child level of this element.
78: */
79: public function folderlist()
80: {
81: $folders = array();
82: $imap_tree = $GLOBALS['injector']->getInstance('IMP_Imap_Tree');
83:
84: $imap_tree->setIteratorFilter(IMP_Imap_Tree::FLIST_NOCONTAINER);
85: foreach ($imap_tree as $val) {
86: $folders[$val->value] = array(
87: 'label' => $val->label,
88: 'level' => $val->level
89: );
90: }
91:
92: return $folders;
93: }
94:
95: /**
96: * Creates a new folder.
97: *
98: * @param string $folder The name of the folder to create (UTF7-IMAP).
99: * @param array $options Additional options:
100: * - full: (boolean) If true, $folder is a full mailbox name. If false,
101: * $folder will be created in the default namespace.
102: * Available since IMP 5.0.11
103: * DEFAULT: false
104: *
105: * @return string The full folder name created or false on failure.
106: *
107: * @throws IMP_Exception
108: */
109: public function createFolder($folder, array $options = array())
110: {
111: $fname = IMP_Mailbox::get($folder);
112: if (empty($options['full'])) {
113: $fname = $fname->namespace_append;
114: }
115:
116: return $fname->create()
117: ? strval($fname)
118: : false;
119: }
120:
121: /**
122: * Deletes messages from a mailbox.
123: *
124: * @param string $mailbox The name of the mailbox (UTF7-IMAP).
125: * @param array $indices The list of UIDs to delete.
126: *
127: * @return integer|boolean The number of messages deleted if successful,
128: * false if not.
129: */
130: public function deleteMessages($mailbox, $indices)
131: {
132: return $GLOBALS['injector']->getInstance('IMP_Message')->delete(
133: new IMP_Indices($mailbox, $indices),
134: array('nuke' => true)
135: );
136: }
137:
138: /**
139: * Copies messages to a mailbox.
140: *
141: * @param string $mailbox The name of the source mailbox (UTF7-IMAP).
142: * @param array $indices The list of UIDs to copy.
143: * @param string $target The name of the target mailbox (UTF7-IMAP).
144: *
145: * @return boolean True if successful, false if not.
146: */
147: public function copyMessages($mailbox, $indices, $target)
148: {
149: return $GLOBALS['injector']->getInstance('IMP_Message')->copy(
150: $target,
151: 'copy',
152: new IMP_Indices($mailbox, $indices),
153: array('create' => true)
154: );
155: }
156:
157: /**
158: * Moves messages to a mailbox.
159: *
160: * @param string $mailbox The name of the source mailbox (UTF7-IMAP).
161: * @param array $indices The list of UIDs to move.
162: * @param string $target The name of the target mailbox (UTF7-IMAP).
163: *
164: * @return boolean True if successful, false if not.
165: */
166: public function moveMessages($mailbox, $indices, $target)
167: {
168: return $GLOBALS['injector']->getInstance('IMP_Message')->copy(
169: $target,
170: 'move',
171: new IMP_Indices($mailbox, $indices),
172: array('create' => true)
173: );
174: }
175:
176: /**
177: * Flag messages.
178: *
179: * @param string $mailbox The name of the source mailbox (UTF7-IMAP).
180: * @param array $indices The list of UIDs to flag.
181: * @param array $flags The flags to set.
182: * @param boolean $set True to set flags, false to clear flags.
183: *
184: * @return boolean True if successful, false if not.
185: */
186: public function flagMessages($mailbox, $indices, $flags, $set)
187: {
188: return $GLOBALS['injector']->getInstance('IMP_Message')->flag(
189: $flags,
190: new IMP_Indices($mailbox, $indices),
191: $set
192: );
193: }
194:
195: /**
196: * Perform a search query on the remote IMAP server.
197: *
198: * @param string $mailbox The name of the source
199: * mailbox (UTF7-IMAP).
200: * @param Horde_Imap_Client_Search_Query $query The query object.
201: *
202: * @return array The search results (UID list).
203: */
204: public function searchMailbox($mailbox, $query)
205: {
206: $results = IMP_Mailbox::get($mailbox)->runSearchQuery($query);
207: return isset($results[$mailbox])
208: ? $results[$mailbox]
209: : array();
210: }
211:
212: /**
213: * Returns information on the currently logged on IMAP server.
214: *
215: * @return mixed An array with the following entries:
216: * <pre>
217: * 'hostspec' - (string) The server hostname.
218: * 'port' - (integer) The server port.
219: * 'protocol' - (string) Either 'imap' or 'pop'.
220: * 'secure' - (string) Either 'none', 'ssl', or 'tls'.
221: * </pre>
222: */
223: public function server()
224: {
225: $imap_ob = $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create();
226:
227: return array(
228: 'hostspec' => $imap_ob->ob->getParam('hostspec'),
229: 'port' => $imap_ob->ob->getParam('port'),
230: 'protocol' => $imap_ob->pop3 ? 'pop' : 'imap',
231: 'secure' => $imap_ob->ob->getParam('secure')
232: );
233: }
234:
235: /**
236: * Returns the list of favorite recipients.
237: *
238: * @param integer $limit Return this number of recipients.
239: * @param array $filter A list of messages types that should be
240: * returned. Valid types: 'forward', 'mdn', 'new',
241: * 'reply', and 'redirect'. A value of null returns
242: * all message types.
243: *
244: * @return array A list with the $limit most favourite recipients.
245: * @throws IMP_Exception
246: */
247: public function favouriteRecipients($limit,
248: $filter = array('new', 'forward', 'reply', 'redirect'))
249: {
250: if (!empty($filter)) {
251: $new_filter = array();
252: foreach ($filter as $val) {
253: switch ($val) {
254: case 'forward':
255: $new_filter[] = IMP_Sentmail::FORWARD;
256: break;
257:
258: case 'mdn':
259: $new_filter[] = IMP_Sentmail::MDN;
260: break;
261:
262: case 'new':
263: $new_filter[] = IMP_Sentmail::NEWMSG;
264: break;
265:
266: case 'redirect':
267: $new_filter[] = IMP_Sentmail::REDIRECT;
268: break;
269:
270: case 'reply':
271: $new_filter[] = IMP_Sentmail::REPLY;
272: break;
273: }
274: }
275:
276: $filter = $new_filter;
277: }
278:
279: return $GLOBALS['injector']->getInstance('IMP_Sentmail')->favouriteRecipients($limit, $filter);
280: }
281:
282: /**
283: * Returns the Horde_Imap_Client object created using the IMP credentials.
284: *
285: * @return Horde_Imap_Client_Base The imap object.
286: */
287: public function imapOb()
288: {
289: return $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create()->ob;
290: }
291:
292: /**
293: * Return the list of user-settable IMAP flags.
294: *
295: * @param string $mailbox If set, returns the list of flags filtered by
296: * what the mailbox allows.
297: *
298: * @return array A list of IMP_Flag_Base objects.
299: */
300: public function flagList($mailbox = null)
301: {
302: if (!$GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create()->access(IMP_Imap::ACCESS_FLAGS)) {
303: return array();
304: }
305:
306: return $GLOBALS['injector']->getInstance('IMP_Flags')->getList(array(
307: 'imap' => true,
308: 'mailbox' => $mailbox
309: ));
310: }
311:
312: }
313: