479 lines
15 KiB
PHP
479 lines
15 KiB
PHP
<?php
|
|
/**
|
|
* Copyright 2009-2017 Horde LLC (http://www.horde.org/)
|
|
*
|
|
* See the enclosed file COPYING for license information (GPL). If you
|
|
* did not receive this file, see http://www.horde.org/licenses/gpl.
|
|
*
|
|
* @category Horde
|
|
* @copyright 2009-2017 Horde LLC
|
|
* @license http://www.horde.org/licenses/gpl GPL
|
|
* @package IMP
|
|
*/
|
|
|
|
/**
|
|
* IMP external API interface.
|
|
*
|
|
* This file defines IMP's external API interface. Other applications
|
|
* can interact with IMP through this API.
|
|
*
|
|
* @author Michael Slusarz <slusarz@horde.org>
|
|
* @category Horde
|
|
* @copyright 2009-2017 Horde LLC
|
|
* @license http://www.horde.org/licenses/gpl GPL
|
|
* @package IMP
|
|
*/
|
|
class IMP_Api extends Horde_Registry_Api
|
|
{
|
|
/**
|
|
* The listing of API calls that do not require permissions checking.
|
|
*
|
|
* @var array
|
|
*/
|
|
protected $_noPerms = array(
|
|
'compose', 'batchCompose'
|
|
);
|
|
|
|
/**
|
|
* Returns a compose window link.
|
|
*
|
|
* @param string|array $args List of arguments to pass to compose page.
|
|
* If this is passed in as a string, it will be
|
|
* parsed as a
|
|
* toaddress?subject=foo&cc=ccaddress
|
|
* (mailto-style) string.
|
|
* @param array $extra Hash of extra, non-standard arguments to
|
|
* pass to compose page.
|
|
*
|
|
* @return Horde_Url The link to the message composition screen.
|
|
*/
|
|
public function compose($args = array(), $extra = array())
|
|
{
|
|
$link = $this->batchCompose(array($args), array($extra));
|
|
return $link[0];
|
|
}
|
|
|
|
/**
|
|
* Return a list of compose window links.
|
|
*
|
|
* @param string|array $args List of arguments to pass to compose page.
|
|
* If this is passed in as a string, it will be
|
|
* parsed as a
|
|
* toaddress?subject=foo&cc=ccaddress
|
|
* (mailto-style) string.
|
|
* @param array $extra List of hashes of extra, non-standard
|
|
* arguments to pass to compose page.
|
|
*
|
|
* @return array The list of Horde_Url objects with links to the message
|
|
* composition screen.
|
|
*/
|
|
public function batchCompose($args = array(), $extra = array())
|
|
{
|
|
$links = array();
|
|
foreach ($args as $i => $arg) {
|
|
$tmp = new IMP_Compose_Link($arg);
|
|
$links[$i] = $tmp->link();
|
|
if (!empty($extra[$i])) {
|
|
$links[$i]->add($extra[$i]);
|
|
}
|
|
}
|
|
return $links;
|
|
}
|
|
|
|
/**
|
|
* Returns the list of mailboxes.
|
|
*
|
|
* @param array $opts Additional options:
|
|
* - reload: (boolean) If true, force reloading the folder tree from
|
|
* the IMAP server. DEFAULT: false
|
|
* @since 6.2.17
|
|
* @return array The list of IMAP mailboxes. A list of arrays with the
|
|
* following keys:
|
|
* - d: (string) The namespace delimiter.
|
|
* - label: (string) Human readable label (UTF-8).
|
|
* - level: (integer) The child level of this element.
|
|
* - ob: (Horde_Imap_Client_Mailbox) A mailbox object.
|
|
* - subscribed: (boolean) True if mailbox is subscribed (@since 6.2.0).
|
|
*/
|
|
public function mailboxList($opts = array())
|
|
{
|
|
global $injector;
|
|
|
|
$ftree = $injector->getInstance('IMP_Ftree');
|
|
if (!empty($opts['reload'])) {
|
|
$ftree->init();
|
|
}
|
|
|
|
$iterator = new IMP_Ftree_IteratorFilter($ftree);
|
|
$iterator->add(array(
|
|
$iterator::CONTAINERS,
|
|
$iterator::REMOTE,
|
|
$iterator::VFOLDER
|
|
));
|
|
$mboxes = array();
|
|
|
|
foreach ($iterator as $val) {
|
|
$mbox_ob = $val->mbox_ob;
|
|
$sub = $mbox_ob->sub;
|
|
|
|
$mboxes[] = array(
|
|
// TODO: Remove for IMP 7.
|
|
'a' => $sub ? 8 : 0,
|
|
'd' => $mbox_ob->namespace_delimiter,
|
|
'label' => $mbox_ob->label,
|
|
'level' => $val->level,
|
|
'ob' => $mbox_ob->imap_mbox_ob,
|
|
'subscribed' => $sub
|
|
);
|
|
}
|
|
|
|
return $mboxes;
|
|
}
|
|
|
|
/**
|
|
* Creates a new mailbox.
|
|
*
|
|
* @param string $mbox The name of the mailbox to create (UTF-8).
|
|
* @param array $options Additional options:
|
|
* - full: (boolean) If true, $mbox is a full mailbox name. If false,
|
|
* $mbox will be created in the default namespace.
|
|
* DEFAULT: false
|
|
*
|
|
* @return Horde_Imap_Client_Mailbox The mailbox name created or false on
|
|
* failure.
|
|
*
|
|
* @throws IMP_Exception
|
|
*/
|
|
public function createMailbox($mbox, array $options = array())
|
|
{
|
|
$fname = IMP_Mailbox::get($mbox);
|
|
if (empty($options['full'])) {
|
|
$fname = $fname->namespace_append;
|
|
}
|
|
|
|
return $fname->create()
|
|
? $fname->imap_mbox_ob
|
|
: false;
|
|
}
|
|
|
|
/**
|
|
* Deletes messages from a mailbox.
|
|
*
|
|
* @param string $mailbox The name of the mailbox (UTF-8).
|
|
* @param array $indices The list of UIDs to delete.
|
|
*
|
|
* @return integer|boolean The number of messages deleted if successful,
|
|
* false if not.
|
|
*/
|
|
public function deleteMessages($mailbox, $indices)
|
|
{
|
|
return $GLOBALS['injector']->getInstance('IMP_Message')->delete(
|
|
new IMP_Indices($mailbox, $indices),
|
|
array('nuke' => true)
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Copies messages to a mailbox.
|
|
*
|
|
* @param string $mailbox The name of the source mailbox (UTF-8).
|
|
* @param array $indices The list of UIDs to copy.
|
|
* @param string $target The name of the target mailbox (UTF-8).
|
|
*
|
|
* @return boolean True if successful, false if not.
|
|
*/
|
|
public function copyMessages($mailbox, $indices, $target)
|
|
{
|
|
return $GLOBALS['injector']->getInstance('IMP_Message')->copy(
|
|
$target,
|
|
'copy',
|
|
new IMP_Indices($mailbox, $indices),
|
|
array('create' => true)
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Moves messages to a mailbox.
|
|
*
|
|
* @param string $mailbox The name of the source mailbox (UTF-8).
|
|
* @param array $indices The list of UIDs to move.
|
|
* @param string $target The name of the target mailbox (UTF-8).
|
|
*
|
|
* @return boolean True if successful, false if not.
|
|
*/
|
|
public function moveMessages($mailbox, $indices, $target)
|
|
{
|
|
return $GLOBALS['injector']->getInstance('IMP_Message')->copy(
|
|
$target,
|
|
'move',
|
|
new IMP_Indices($mailbox, $indices),
|
|
array('create' => true)
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Flag messages.
|
|
*
|
|
* @param string $mailbox The name of the source mailbox (UTF-8).
|
|
* @param array $indices The list of UIDs to flag.
|
|
* @param array $flags The flags to set.
|
|
* @param boolean $set True to set flags, false to clear flags.
|
|
*
|
|
* @return boolean True if successful, false if not.
|
|
*/
|
|
public function flagMessages($mailbox, $indices, $flags, $set)
|
|
{
|
|
return $GLOBALS['injector']->getInstance('IMP_Message')->flag(array(
|
|
($set ? 'add' : 'remove') => $flags
|
|
), new IMP_Indices($mailbox, $indices));
|
|
}
|
|
|
|
/**
|
|
* Perform a search query on the remote IMAP server.
|
|
*
|
|
* @param string $mailbox The name of the source
|
|
* mailbox (UTF-8).
|
|
* @param Horde_Imap_Client_Search_Query $query The query object.
|
|
*
|
|
* @return array The search results (UID list).
|
|
*/
|
|
public function searchMailbox($mailbox, $query)
|
|
{
|
|
$results = IMP_Mailbox::get($mailbox)->runSearchQuery($query);
|
|
return isset($results[strval($mailbox)])
|
|
? $results[strval($mailbox)]
|
|
: array();
|
|
}
|
|
|
|
/**
|
|
* Returns information on the currently logged on IMAP server.
|
|
*
|
|
* @return mixed An array with the following entries:
|
|
* - hostspec: (string) The server hostname.
|
|
* - port: (integer) The server port.
|
|
* - protocol: (string) Either 'imap' or 'pop'.
|
|
* - secure: (string) Either 'none', 'ssl', or 'tls'.
|
|
*/
|
|
public function server()
|
|
{
|
|
$imap_ob = $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create();
|
|
|
|
return array(
|
|
'hostspec' => $imap_ob->getParam('hostspec'),
|
|
'port' => $imap_ob->getParam('port'),
|
|
'protocol' => $imap_ob->isImap() ? 'imap' : 'pop',
|
|
'secure' => $imap_ob->getParam('secure')
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns the list of favorite recipients.
|
|
*
|
|
* @param integer $limit Return this number of recipients.
|
|
* @param array $filter A list of messages types that should be
|
|
* returned. Valid types: 'forward', 'mdn', 'new',
|
|
* 'reply', and 'redirect'. A value of null returns
|
|
* all message types.
|
|
*
|
|
* @return array A list with the $limit most favourite recipients.
|
|
* @throws IMP_Exception
|
|
*/
|
|
public function favouriteRecipients($limit,
|
|
$filter = array('new', 'forward', 'reply', 'redirect'))
|
|
{
|
|
if (!empty($filter)) {
|
|
$new_filter = array();
|
|
foreach ($filter as $val) {
|
|
switch ($val) {
|
|
case 'forward':
|
|
$new_filter[] = IMP_Sentmail::FORWARD;
|
|
break;
|
|
|
|
case 'mdn':
|
|
$new_filter[] = IMP_Sentmail::MDN;
|
|
break;
|
|
|
|
case 'new':
|
|
$new_filter[] = IMP_Sentmail::NEWMSG;
|
|
break;
|
|
|
|
case 'redirect':
|
|
$new_filter[] = IMP_Sentmail::REDIRECT;
|
|
break;
|
|
|
|
case 'reply':
|
|
$new_filter[] = IMP_Sentmail::REPLY;
|
|
break;
|
|
}
|
|
}
|
|
|
|
$filter = $new_filter;
|
|
}
|
|
|
|
return $GLOBALS['injector']->getInstance('IMP_Sentmail')->favouriteRecipients($limit, $filter);
|
|
}
|
|
|
|
/**
|
|
* Log an entry to the IMP_Sentmail system.
|
|
*
|
|
* @param string $action The performed action. One of:
|
|
* <pre>
|
|
* - forward
|
|
* - mdn
|
|
* - new
|
|
* - redirect
|
|
* - reply
|
|
* </pre>
|
|
* @param string|array $recipients The message recipients.
|
|
* @param string $message_id The Message-ID.
|
|
* @param boolean $success Was the message successfully sent?
|
|
*/
|
|
public function logRecipient(
|
|
$reason, $recipients, $message_id, $success = true
|
|
)
|
|
{
|
|
$GLOBALS['injector']->getInstance('IMP_Sentmail')->log(
|
|
$reason,
|
|
$message_id,
|
|
$recipients,
|
|
$success
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns the Horde_Imap_Client object created using the IMP credentials.
|
|
*
|
|
* @return Horde_Imap_Client_Base The imap object.
|
|
*/
|
|
public function imapOb()
|
|
{
|
|
return $GLOBALS['injector']->getInstance('IMP_Factory_Imap')->create()->client_ob;
|
|
}
|
|
|
|
/**
|
|
* Return the list of user-settable IMAP flags.
|
|
*
|
|
* @param string $mailbox If set, returns the list of flags filtered by
|
|
* what the mailbox allows (UTF-8).
|
|
*
|
|
* @return array A list of IMP_Flag_Base objects.
|
|
*/
|
|
public function flagList($mailbox = null)
|
|
{
|
|
return $GLOBALS['injector']->getInstance('IMP_Flags')->getList(array(
|
|
'imap' => true,
|
|
'mailbox' => $mailbox
|
|
));
|
|
}
|
|
|
|
/**
|
|
* Return the list of special mailboxes.
|
|
*
|
|
* @return @see IMP_Mailbox::getSpecialMailboxes()
|
|
*/
|
|
public function getSpecialMailboxes()
|
|
{
|
|
return IMP_Mailbox::getSpecialMailboxes();
|
|
}
|
|
|
|
/**
|
|
* Obtain the Maillog for a given message.
|
|
*
|
|
* @since 6.1.0
|
|
* @todo This should not be returning a Horde_History_Log object.
|
|
*
|
|
* @param string $mid The Message-ID to obtain the log for.
|
|
*
|
|
* @return Horde_History_Log The log object.
|
|
*/
|
|
public function getMaillog($mid)
|
|
{
|
|
global $injector, $registry;
|
|
|
|
$log = $injector->getInstance('IMP_Maillog')->getLog(
|
|
new IMP_Maillog_Message($mid)
|
|
);
|
|
|
|
$history = array();
|
|
foreach ($log as $val) {
|
|
$history[] = array(
|
|
'history_action' => $val->action,
|
|
'history_desc' => '',
|
|
'history_id' => 0,
|
|
'history_modseq' => 0,
|
|
'history_ts' => $val->timestamp,
|
|
'history_who' => $registry->getAuth()
|
|
);
|
|
}
|
|
|
|
return new Horde_History_Log($mid, $history);
|
|
}
|
|
|
|
/**
|
|
* Log an entry in the Maillog.
|
|
*
|
|
* @since 6.1.0
|
|
* @todo Rewrite this. $action and $data are both IMP specific, so they
|
|
* aren't intended to be set from outside of IMP. And $mid should
|
|
* be replaced by mailbox/UID.
|
|
*
|
|
* @param string $action The action to log.
|
|
* @param string $mid The Message-ID.
|
|
* @param string $data Additional data.
|
|
*/
|
|
public function logMaillog($action, $mid, $data = null)
|
|
{
|
|
switch ($action) {
|
|
case 'forward':
|
|
$log = new IMP_Maillog_Log_Forward($data['recipients']);
|
|
break;
|
|
|
|
case 'mdn':
|
|
$log = new IMP_Maillog_Log_Mdn();
|
|
break;
|
|
|
|
case 'redirect':
|
|
$log = new IMP_Maillog_Log_Redirect($data['recipients']);
|
|
break;
|
|
|
|
case 'reply':
|
|
$log = new IMP_Maillog_Log_Reply();
|
|
break;
|
|
|
|
case 'reply_all':
|
|
$log = new IMP_Maillog_Log_Replyall();
|
|
break;
|
|
|
|
case 'reply_list':
|
|
$log = new IMP_Maillog_Log_Replylist();
|
|
break;
|
|
}
|
|
|
|
$GLOBALS['injector']->getInstance('IMP_Maillog')->log(
|
|
new IMP_Maillog_Message($mid),
|
|
$log
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns a list of Message-IDs that have been added to the Maillog since
|
|
* the specified timestamp.
|
|
*
|
|
* @since 6.1.0
|
|
* @todo This should not be returning Message-IDs.
|
|
*
|
|
* @param integer $ts The timestamp to start searching from. Only entries
|
|
* after this timestamp will be returned.
|
|
*
|
|
* @return array An array of Message-IDs that have been changed since $ts.
|
|
*/
|
|
public function getMaillogChanges($ts)
|
|
{
|
|
return array_map(
|
|
'strval',
|
|
$GLOBALS['injector']->getInstance('IMP_Maillog')->getChanges($ts)
|
|
);
|
|
}
|
|
|
|
}
|