Documentation, code style and cleanup

thomascube

2007-08-07 6d969b4d9020560d3491d19a5b0487e325e9bce4

 program/include/rcube_imap.inc

@@ -21,7 +21,7 @@
*/


/**
/*
 * Obtain classes from the Iloha IMAP library
 */
require_once('lib/imap.inc');
@@ -33,7 +33,7 @@
 *
 * 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
@@ -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,7 +414,7 @@
   * @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
   * @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,7 +1242,7 @@
   * 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)
    {
@@ -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;
@@ -1826,7 +1889,9 @@
    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();
@@ -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)
  {