From 6d969b4d9020560d3491d19a5b0487e325e9bce4 Mon Sep 17 00:00:00 2001
From: thomascube <thomas@roundcube.net>
Date: Tue, 07 Aug 2007 17:02:12 -0400
Subject: [PATCH] Documentation, code style and cleanup
---
program/include/rcube_imap.inc | 377 +++++++++++++++++++++++++++++++++++++----------------
1 files changed, 262 insertions(+), 115 deletions(-)
diff --git a/program/include/rcube_imap.inc b/program/include/rcube_imap.inc
index 9ca6cf5..0cfda15 100644
--- a/program/include/rcube_imap.inc
+++ b/program/include/rcube_imap.inc
@@ -21,7 +21,7 @@
*/
-/**
+/*
* Obtain classes from the Iloha IMAP library
*/
require_once('lib/imap.inc');
@@ -33,13 +33,13 @@
*
* This is a wrapper that implements the Iloha IMAP Library (IIL)
*
- * @package RoundCube Webmail
+ * @package Mail
* @author Thomas Bruederli <roundcube@gmail.com>
* @version 1.36
* @link http://ilohamail.org
*/
class rcube_imap
- {
+{
var $db;
var $conn;
var $root_ns = '';
@@ -70,7 +70,7 @@
/**
* Object constructor
*
- * @param object Database connection
+ * @param object DB Database connection
*/
function __construct($db_conn)
{
@@ -294,6 +294,7 @@
/**
* Return the saved search set as hash array
+ * @return array Search set
*/
function get_search_set()
{
@@ -382,8 +383,8 @@
* Private method for mailbox listing
*
* @return array List of mailboxes/folders
+ * @see rcube_imap::list_mailboxes()
* @access private
- * @see rcube_imap::list_mailboxes
*/
function _list_mailboxes($root='', $filter='*')
{
@@ -413,8 +414,8 @@
* @param string Mailbox/folder name
* @param string Mode for count [ALL|UNSEEN|RECENT]
* @param boolean Force reading from server and update cache
- * @return number Number of messages
- * @access public
+ * @return int Number of messages
+ * @access public
*/
function messagecount($mbox_name='', $mode='ALL', $force=FALSE)
{
@@ -427,7 +428,7 @@
* Private method for getting nr of messages
*
* @access private
- * @see rcube_imap::messagecount
+ * @see rcube_imap::messagecount()
*/
function _messagecount($mailbox='', $mode='ALL', $force=FALSE)
{
@@ -496,7 +497,7 @@
* convert mailbox name with root dir first
*
* @param string Mailbox/folder name
- * @param number Current page to list
+ * @param int Current page to list
* @param string Header field to sort by
* @param string Sort order [ASC|DESC]
* @return array Indexed array with message header objects
@@ -616,7 +617,7 @@
*
* @param string Mailbox/folder name
* @param array List of message ids to list
- * @param number Current page to list
+ * @param int Current page to list
* @param string Header field to sort by
* @param string Sort order [ASC|DESC]
* @return array Indexed array with message header objects
@@ -633,7 +634,7 @@
* Private method for listing a set of message headers
*
* @access private
- * @see rcube_imap::list_header_set
+ * @see rcube_imap::list_header_set()
*/
function _list_header_set($mailbox, $msgs, $page=NULL, $sort_field=NULL, $sort_order=NULL)
{
@@ -671,7 +672,7 @@
/**
* Helper function to get first and last index of the requested set
*
- * @param number message count
+ * @param int message count
* @param mixed page number to show, or string 'all'
* @return array array with two values: first index, last index
* @access private
@@ -713,7 +714,7 @@
* @param string Message index to fetch
* @param array Reference to message headers array
* @param array Array with cache index
- * @return number Number of deleted messages
+ * @return int Number of deleted messages
* @access private
*/
function _fetch_headers($mailbox, $msgs, &$a_msg_headers, $cache_key)
@@ -815,6 +816,9 @@
}
+ /**
+ * @access private
+ */
function sync_header_index($mailbox)
{
$cache_key = $mailbox.'.msg';
@@ -927,6 +931,8 @@
/**
* Refresh saved search set
+ *
+ * @return array Current search set
*/
function refresh_search()
{
@@ -973,8 +979,8 @@
* Fetch body structure from the IMAP server and build
* an object structure similar to the one generated by PEAR::Mail_mimeDecode
*
- * @param Int Message UID to fetch
- * @return object Standard object tree or False on failure
+ * @param int Message UID to fetch
+ * @return object stdClass Message part tree or False on failure
*/
function &get_structure($uid)
{
@@ -1136,7 +1142,7 @@
/**
* Return a flat array with references to all parts, indexed by part numbers
*
- * @param object Message body structure
+ * @param object rcube_message_part Message body structure
* @return Array with part number -> object pairs
*/
function get_mime_numbers(&$structure)
@@ -1150,7 +1156,7 @@
/**
* Helper method for recursive calls
*
- * @access
+ * @access private
*/
function _get_part_numbers(&$part, &$a_parts)
{
@@ -1168,9 +1174,9 @@
*
* @param int Message UID
* @param string Part number
- * @param object Part object created by get_structure()
+ * @param object rcube_message_part Part object created by get_structure()
* @param mixed True to print part, ressource to write part contents in
- * @return Message/part body if not printed
+ * @return string Message/part body if not printed
*/
function &get_message_part($uid, $part=1, $o_part=NULL, $print=NULL)
{
@@ -1223,8 +1229,8 @@
* Fetch message body of a specific message from the server
*
* @param int Message UID
- * @return Message/part body
- * @see ::get_message_part()
+ * @return string Message/part body
+ * @see rcube_imap::get_message_part()
*/
function &get_body($uid, $part=1)
{
@@ -1236,15 +1242,15 @@
* Returns the whole message source as string
*
* @param int Message UID
- * @return Message source string
+ * @return string Message source string
*/
function &get_raw_body($uid)
{
if (!($msg_id = $this->_uid2id($uid)))
return FALSE;
- $body = iil_C_FetchPartHeader($this->conn, $this->mailbox, $msg_id, NULL);
- $body .= iil_C_HandlePartBody($this->conn, $this->mailbox, $msg_id, NULL, 1);
+ $body = iil_C_FetchPartHeader($this->conn, $this->mailbox, $msg_id, NULL);
+ $body .= iil_C_HandlePartBody($this->conn, $this->mailbox, $msg_id, NULL, 1);
return $body;
}
@@ -1260,9 +1266,9 @@
if (!($msg_id = $this->_uid2id($uid)))
return FALSE;
- print iil_C_FetchPartHeader($this->conn, $this->mailbox, $msg_id, NULL);
- flush();
- iil_C_HandlePartBody($this->conn, $this->mailbox, $msg_id, NULL, 2);
+ print iil_C_FetchPartHeader($this->conn, $this->mailbox, $msg_id, NULL);
+ flush();
+ iil_C_HandlePartBody($this->conn, $this->mailbox, $msg_id, NULL, 2);
}
@@ -1271,7 +1277,7 @@
*
* @param mixed Message UIDs as array or as comma-separated string
* @param string Flag to set: SEEN, UNDELETED, DELETED, RECENT, ANSWERED, DRAFT
- * @return True on success, False on failure
+ * @return boolean True on success, False on failure
*/
function set_flag($uids, $flag)
{
@@ -1324,7 +1330,13 @@
}
- // append a mail message (source) to a specific mailbox
+ /**
+ * Append a mail message (source) to a specific mailbox
+ *
+ * @param string Target mailbox
+ * @param string Message source
+ * @return boolean True on success, False on error
+ */
function save_message($mbox_name, &$message)
{
$mbox_name = stripslashes($mbox_name);
@@ -1344,7 +1356,14 @@
}
- // move a message from one mailbox to another
+ /**
+ * Move a message from one mailbox to another
+ *
+ * @param string List of UIDs to move, separated by comma
+ * @param string Target mailbox
+ * @param string Source mailbox
+ * @return boolean True on success, False on error
+ */
function move_message($uids, $to_mbox, $from_mbox='')
{
$to_mbox = stripslashes($to_mbox);
@@ -1408,7 +1427,13 @@
}
- // mark messages as deleted and expunge mailbox
+ /**
+ * Mark messages as deleted and expunge mailbox
+ *
+ * @param string List of UIDs to move, separated by comma
+ * @param string Source mailbox
+ * @return boolean True on success, False on error
+ */
function delete_message($uids, $mbox_name='')
{
$mbox_name = stripslashes($mbox_name);
@@ -1460,7 +1485,12 @@
}
- // clear all messages in a specific mailbox
+ /**
+ * Clear all messages in a specific mailbox
+ *
+ * @param string Mailbox name
+ * @return int Above 0 on success
+ */
function clear_mailbox($mbox_name=NULL)
{
$mbox_name = stripslashes($mbox_name);
@@ -1487,7 +1517,13 @@
}
- // send IMAP expunge command and clear cache
+ /**
+ * Send IMAP expunge command and clear cache
+ *
+ * @param string Mailbox name
+ * @param boolean False if cache should not be cleared
+ * @return boolean True on success
+ */
function expunge($mbox_name='', $clear_cache=TRUE)
{
$mbox_name = stripslashes($mbox_name);
@@ -1496,7 +1532,12 @@
}
- // send IMAP expunge command and clear cache
+ /**
+ * Send IMAP expunge command and clear cache
+ *
+ * @see rcube_imap::expunge()
+ * @access private
+ */
function _expunge($mailbox, $clear_cache=TRUE)
{
$result = iil_C_Expunge($this->conn, $mailbox);
@@ -1520,7 +1561,7 @@
* Get a list of all folders available on the IMAP server
*
* @param string IMAP root dir
- * @return array Inbdexed array with folder names
+ * @return array Indexed array with folder names
*/
function list_unsubscribed($root='')
{
@@ -1547,8 +1588,10 @@
/**
- * Get quota
+ * Get mailbox quota information
* added by Nuny
+ *
+ * @return mixed Quota info or False if not supported
*/
function get_quota()
{
@@ -1560,9 +1603,12 @@
/**
- * subscribe to a specific mailbox(es)
+ * Subscribe to a specific mailbox(es)
+ *
+ * @param string Mailbox name(s)
+ * @return boolean True on success
*/
- function subscribe($mbox_name, $mode='subscribe')
+ function subscribe($mbox_name)
{
if (is_array($mbox_name))
$a_mboxes = $mbox_name;
@@ -1575,7 +1621,10 @@
/**
- * unsubscribe mailboxes
+ * Unsubscribe mailboxes
+ *
+ * @param string Mailbox name(s)
+ * @return boolean True on success
*/
function unsubscribe($mbox_name)
{
@@ -1625,7 +1674,7 @@
*
* @param string Mailbox to rename (as utf-7 string)
* @param string New mailbox name (as utf-7 string)
- * @param string Name of the renames mailbox, false on error
+ * @return string Name of the renames mailbox, False on error
*/
function rename_mailbox($mbox_name, $new_name)
{
@@ -1668,7 +1717,10 @@
/**
- * remove mailboxes from server
+ * Remove mailboxes from server
+ *
+ * @param string Mailbox name
+ * @return boolean True on success
*/
function delete_mailbox($mbox_name)
{
@@ -1736,7 +1788,9 @@
* internal caching methods
* --------------------------------*/
-
+ /**
+ * @access private
+ */
function set_caching($set)
{
if ($set && is_object($this->db))
@@ -1745,7 +1799,9 @@
$this->caching_enabled = FALSE;
}
-
+ /**
+ * @access private
+ */
function get_cache($key)
{
// read cache
@@ -1758,7 +1814,9 @@
return $this->cache[$key];
}
-
+ /**
+ * @access private
+ */
function update_cache($key, $data)
{
$this->cache[$key] = $data;
@@ -1766,7 +1824,9 @@
$this->cache_changes[$key] = TRUE;
}
-
+ /**
+ * @access private
+ */
function write_cache()
{
if ($this->caching_enabled && $this->cache_changed)
@@ -1779,7 +1839,9 @@
}
}
-
+ /**
+ * @access private
+ */
function clear_cache($key=NULL)
{
if ($key===NULL)
@@ -1799,8 +1861,9 @@
}
}
-
-
+ /**
+ * @access private
+ */
function _read_cache_record($key)
{
$cache_data = FALSE;
@@ -1823,10 +1886,12 @@
}
}
- return $cache_data;
+ return $cache_data;
}
-
+ /**
+ * @access private
+ */
function _write_cache_record($key, $data)
{
if (!$this->db)
@@ -1875,7 +1940,9 @@
}
}
-
+ /**
+ * @access private
+ */
function _clear_cache_record($key)
{
$this->db->query(
@@ -1893,8 +1960,13 @@
* --------------------------------*/
- // checks if the cache is up-to-date
- // return: -3 = off, -2 = incomplete, -1 = dirty
+ /**
+ * Checks if the cache is up-to-date
+ *
+ * @param string Mailbox name
+ * @param string Internal cache key
+ * @return int -3 = off, -2 = incomplete, -1 = dirty
+ */
function check_cache_status($mailbox, $cache_key)
{
if (!$this->caching_enabled)
@@ -1926,8 +1998,9 @@
return -2;
}
-
-
+ /**
+ * @access private
+ */
function get_message_cache($key, $from, $to, $sort_field, $sort_order)
{
$cache_key = "$key:$from:$to:$sort_field:$sort_order";
@@ -1961,7 +2034,9 @@
return $this->cache[$cache_key];
}
-
+ /**
+ * @access private
+ */
function &get_cached_message($key, $uid, $struct=false)
{
if (!$this->caching_enabled)
@@ -1993,7 +2068,9 @@
return $this->cache[$internal_key][$uid];
}
-
+ /**
+ * @access private
+ */
function get_message_cache_index($key, $force=FALSE, $sort_col='idx', $sort_order='ASC')
{
static $sa_message_index = array();
@@ -2021,7 +2098,9 @@
return $sa_message_index[$key];
}
-
+ /**
+ * @access private
+ */
function add_message_cache($key, $index, $headers, $struct=null)
{
if (!$this->caching_enabled || empty($key) || !is_object($headers) || empty($headers->uid))
@@ -2073,7 +2152,9 @@
}
}
-
+ /**
+ * @access private
+ */
function remove_message_cache($key, $index)
{
$this->db->query(
@@ -2086,7 +2167,9 @@
$index);
}
-
+ /**
+ * @access private
+ */
function clear_message_cache($key, $start_index=1)
{
$this->db->query(
@@ -2106,7 +2189,14 @@
* encoding/decoding methods
* --------------------------------*/
-
+ /**
+ * Split an address list into a structured array list
+ *
+ * @param string Input string
+ * @param int List only this number of addresses
+ * @param boolean Decode address strings
+ * @return array Indexed list of addresses
+ */
function decode_address_list($input, $max=null, $decode=true)
{
$a = $this->_parse_address_list($input, $decode);
@@ -2142,6 +2232,13 @@
}
+ /**
+ * Decode a message header value
+ *
+ * @param string Header value
+ * @param boolean Remove quotes if necessary
+ * @return string Decoded string
+ */
function decode_header($input, $remove_quotes=FALSE)
{
$str = $this->decode_mime_string((string)$input);
@@ -2155,7 +2252,10 @@
/**
* Decode a mime-encoded string to internal charset
*
- * @access static
+ * @param string Header value
+ * @param string Fallback charset if none specified
+ * @return string Decoded string
+ * @static
*/
function decode_mime_string($input, $fallback=null)
{
@@ -2187,7 +2287,7 @@
/**
* Decode a part of a mime-encoded string
*
- * @access static
+ * @access private
*/
function _decode_mime_string_part($str)
{
@@ -2215,6 +2315,14 @@
}
+ /**
+ * Decode a mime part
+ *
+ * @param string Input string
+ * @param string Part encoding
+ * @return string Decoded string
+ * @access private
+ */
function mime_decode($input, $encoding='7bit')
{
switch (strtolower($encoding))
@@ -2237,25 +2345,13 @@
}
- function mime_encode($input, $encoding='7bit')
- {
- switch ($encoding)
- {
- case 'quoted-printable':
- return quoted_printable_encode($input);
- break;
-
- case 'base64':
- return base64_encode($input);
- break;
-
- default:
- return $input;
- }
- }
-
-
- // convert body chars according to the ctype_parameters
+ /**
+ * Convert body charset to UTF-8 according to the ctype_parameters
+ *
+ * @param string Part body to decode
+ * @param string Charset to convert from
+ * @return string Content converted to internal charset
+ */
function charset_decode($body, $ctype_param)
{
if (is_array($ctype_param) && !empty($ctype_param['charset']))
@@ -2266,6 +2362,33 @@
}
+ /**
+ * Translate UID to message ID
+ *
+ * @param int Message UID
+ * @param string Mailbox name
+ * @return int Message ID
+ */
+ function get_id($uid, $mbox_name=NULL)
+ {
+ $mailbox = $mbox_name ? $this->_mod_mailbox($mbox_name) : $this->mailbox;
+ return $this->_uid2id($uid, $mailbox);
+ }
+
+
+ /**
+ * Translate message number to UID
+ *
+ * @param int Message ID
+ * @param string Mailbox name
+ * @return int Message UID
+ */
+ function get_uid($id,$mbox_name=NULL)
+ {
+ $mailbox = $mbox_name ? $this->_mod_mailbox($mbox_name) : $this->mailbox;
+ return $this->_id2uid($id, $mailbox);
+ }
+
/* --------------------------------
@@ -2273,6 +2396,9 @@
* --------------------------------*/
+ /**
+ * @access private
+ */
function _mod_mailbox($mbox_name, $mode='in')
{
if ((!empty($this->root_ns) && $this->root_ns == $mbox_name) || $mbox_name == 'INBOX')
@@ -2287,7 +2413,10 @@
}
- // sort mailboxes first by default folders and then in alphabethical order
+ /**
+ * Sort mailboxes first by default folders and then in alphabethical order
+ * @access private
+ */
function _sort_mailbox_list($a_folders)
{
$a_out = $a_defaults = array();
@@ -2296,10 +2425,10 @@
foreach($a_folders as $i => $folder)
{
if ($folder{0}=='.')
- continue;
+ continue;
if (($p = array_search(strtolower($folder), $this->default_folders_lc))!==FALSE)
- $a_defaults[$p] = $folder;
+ $a_defaults[$p] = $folder;
else
$a_out[] = $folder;
}
@@ -2310,18 +2439,9 @@
return array_merge($a_defaults, $a_out);
}
- function get_id($uid, $mbox_name=NULL)
- {
- $mailbox = $mbox_name ? $this->_mod_mailbox($mbox_name) : $this->mailbox;
- return $this->_uid2id($uid, $mailbox);
- }
-
- function get_uid($id,$mbox_name=NULL)
- {
- $mailbox = $mbox_name ? $this->_mod_mailbox($mbox_name) : $this->mailbox;
- return $this->_id2uid($id, $mailbox);
- }
-
+ /**
+ * @access private
+ */
function _uid2id($uid, $mbox_name=NULL)
{
if (!$mbox_name)
@@ -2333,6 +2453,9 @@
return $this->uid_id_map[$mbox_name][$uid];
}
+ /**
+ * @access private
+ */
function _id2uid($id, $mbox_name=NULL)
{
if (!$mbox_name)
@@ -2342,7 +2465,10 @@
}
- // parse string or array of server capabilities and put them in internal array
+ /**
+ * Parse string or array of server capabilities and put them in internal array
+ * @access private
+ */
function _parse_capability($caps)
{
if (!is_array($caps))
@@ -2369,7 +2495,10 @@
}
- // subscribe/unsubscribe a list of mailboxes and update local cache
+ /**
+ * Subscribe/unsubscribe a list of mailboxes and update local cache
+ * @access private
+ */
function _change_subscription($a_mboxes, $mode)
{
$updated = FALSE;
@@ -2410,7 +2539,10 @@
}
- // increde/decrese messagecount for a specific mailbox
+ /**
+ * Increde/decrese messagecount for a specific mailbox
+ * @access private
+ */
function _set_messagecount($mbox_name, $mode, $increment)
{
$a_mailbox_cache = FALSE;
@@ -2436,7 +2568,10 @@
}
- // remove messagecount of a specific mailbox from cache
+ /**
+ * Remove messagecount of a specific mailbox from cache
+ * @access private
+ */
function _clear_messagecount($mbox_name='')
{
$a_mailbox_cache = FALSE;
@@ -2452,7 +2587,10 @@
}
- // split RFC822 header string into an associative array
+ /**
+ * Split RFC822 header string into an associative array
+ * @access private
+ */
function _parse_headers($headers)
{
$a_headers = array();
@@ -2473,6 +2611,9 @@
}
+ /**
+ * @access private
+ */
function _parse_address_list($str, $decode=true)
{
// remove any newlines and carriage returns before
@@ -2501,6 +2642,9 @@
}
+ /**
+ * @access private
+ */
function _explode_quoted_string($delimiter, $string)
{
$result = array();
@@ -2519,11 +2663,14 @@
$result[] = substr($string, $p);
return $result;
}
- }
+
+} // end class rcube_imap
/**
* Class representing a message part
+ *
+ * @package Mail
*/
class rcube_message_part
{
@@ -2544,10 +2691,9 @@
/**
- * rcube_header_sorter
- *
* Class for sorting an array of iilBasicHeader objects in a predetermined order.
*
+ * @package Mail
* @author Eric Stadtherr
*/
class rcube_header_sorter
@@ -2555,9 +2701,9 @@
var $sequence_numbers = array();
/**
- * set the predetermined sort order.
+ * Set the predetermined sort order.
*
- * @param array $seqnums numerically indexed array of IMAP message sequence numbers
+ * @param array Numerically indexed array of IMAP message sequence numbers
*/
function set_sequence_numbers($seqnums)
{
@@ -2565,9 +2711,9 @@
}
/**
- * sort the array of header objects
+ * Sort the array of header objects
*
- * @param array $headers array of iilBasicHeader objects indexed by UID
+ * @param array Array of iilBasicHeader objects indexed by UID
*/
function sort_headers(&$headers)
{
@@ -2582,9 +2728,10 @@
}
/**
- * get the position of a message sequence number in my sequence_numbers array
+ * Get the position of a message sequence number in my sequence_numbers array
*
- * @param integer $seqnum message sequence number contained in sequence_numbers
+ * @param int Message sequence number contained in sequence_numbers
+ * @return int Position, -1 if not found
*/
function position_of($seqnum)
{
@@ -2620,10 +2767,10 @@
/**
* Add quoted-printable encoding to a given string
*
- * @param string $input string to encode
- * @param int $line_max add new line after this number of characters
- * @param boolena $space_conf true if spaces should be converted into =20
- * @return encoded string
+ * @param string String to encode
+ * @param int Add new line after this number of characters
+ * @param boolean True if spaces should be converted into =20
+ * @return string Encoded string
*/
function quoted_printable_encode($input, $line_max=76, $space_conv=false)
{
--
Gitblit v1.9.1