Ignore:
Timestamp:
Aug 7, 2007 5:02:12 PM (6 years ago)
Author:
thomasb
Message:

Documentation, code style and cleanup

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/roundcubemail/program/include/main.inc

    r652 r666  
    2020*/ 
    2121 
     22/** 
     23 * RoundCube Webmail common functions 
     24 * 
     25 * @package Core 
     26 * @author Thomas Bruederli <roundcube@gmail.com> 
     27 */ 
     28 
    2229require_once('lib/des.inc'); 
    2330require_once('lib/utf7.inc'); 
     
    3239 
    3340 
    34 // register session and connect to server 
     41/** 
     42 * Initial startup function 
     43 * to register session, create database and imap connections 
     44 * 
     45 * @param string Current task 
     46 */ 
    3547function rcmail_startup($task='mail') 
    3648  { 
     
    4961 
    5062  // prepare DB connection 
    51   require_once('include/rcube_'.(empty($CONFIG['db_backend']) ? 'db' : $CONFIG['db_backend']).'.inc'); 
    52    
    53   $DB = new rcube_db($CONFIG['db_dsnw'], $CONFIG['db_dsnr'], $CONFIG['db_persistent']); 
     63  $dbwrapper = empty($CONFIG['db_backend']) ? 'db' : $CONFIG['db_backend']; 
     64  $dbclass = "rcube_" . $dbwrapper; 
     65  require_once("include/$dbclass.inc"); 
     66   
     67  $DB = new $dbclass($CONFIG['db_dsnw'], $CONFIG['db_dsnr'], $CONFIG['db_persistent']); 
    5468  $DB->sqlite_initials = $INSTALL_PATH.'SQL/sqlite.initial.sql'; 
    5569  $DB->db_connect('w'); 
     
    102116 
    103117 
    104 // load roundcube configuration into global var 
     118/** 
     119 * Load roundcube configuration array 
     120 * 
     121 * @return array Named configuration parameters 
     122 */ 
    105123function rcmail_load_config() 
    106124  { 
     
    140158 
    141159 
    142 // load a host-specific config file if configured 
     160/** 
     161 * Load a host-specific config file if configured 
     162 * This will merge the host specific configuration with the given one 
     163 * 
     164 * @param array Global configuration parameters 
     165 */ 
    143166function rcmail_load_host_config(&$config) 
    144167  { 
     
    158181 
    159182 
    160 // create authorization hash 
     183/** 
     184 * Create unique authorization hash 
     185 * 
     186 * @param string Session ID 
     187 * @param int Timestamp 
     188 * @return string The generated auth hash 
     189 */ 
    161190function rcmail_auth_hash($sess_id, $ts) 
    162191  { 
     
    176205 
    177206 
    178 // compare the auth hash sent by the client with the local session credentials 
     207/** 
     208 * Check the auth hash sent by the client against the local session credentials 
     209 * 
     210 * @return boolean True if valid, False if not 
     211 */ 
    179212function rcmail_authenticate_session() 
    180213  { 
     
    207240 
    208241 
    209 // create IMAP object and connect to server 
     242/** 
     243 * Create global IMAP object and connect to server 
     244 * 
     245 * @param boolean True if connection should be established 
     246 */ 
    210247function rcmail_imap_init($connect=FALSE) 
    211248  { 
     
    236273 
    237274 
    238 // set root dir and last stored mailbox 
    239 // this must be done AFTER connecting to the server 
     275/** 
     276 * Set root dir and last stored mailbox 
     277 * This must be done AFTER connecting to the server! 
     278 */ 
    240279function rcmail_set_imap_prop() 
    241280  { 
     
    256295 
    257296 
    258 // do these things on script shutdown 
     297/** 
     298 * Do these things on script shutdown 
     299 */ 
    259300function rcmail_shutdown() 
    260301  { 
     
    272313 
    273314 
    274 // destroy session data and remove cookie 
     315/** 
     316 * Destroy session data and remove cookie 
     317 */ 
    275318function rcmail_kill_session() 
    276319  { 
     
    293336 
    294337 
    295 // return correct name for a specific database table 
     338/** 
     339 * Return correct name for a specific database table 
     340 * 
     341 * @param string Table name 
     342 * @return string Translated table name 
     343 */ 
    296344function get_table_name($table) 
    297345  { 
     
    308356 
    309357 
    310 // return correct name for a specific database sequence 
    311 // (used for Postres only) 
     358/** 
     359 * Return correct name for a specific database sequence 
     360 * (used for Postres only) 
     361 * 
     362 * @param string Secuence name 
     363 * @return string Translated sequence name 
     364 */ 
    312365function get_sequence_name($sequence) 
    313366  { 
     
    324377 
    325378 
    326 // check the given string and returns language properties 
     379/** 
     380 * Check the given string and returns language properties 
     381 * 
     382 * @param string Language code 
     383 * @param string Peropert name 
     384 * @return string Property value 
     385 */ 
    327386function rcube_language_prop($lang, $prop='lang') 
    328387  { 
     
    361420   
    362421 
    363 // init output object for GUI and add common scripts 
     422/** 
     423 * Init output object for GUI and add common scripts. 
     424 * This will instantiate a rcmail_template object and set 
     425 * environment vars according to the current session and configuration 
     426 */ 
    364427function rcmail_load_gui() 
    365428  { 
     
    400463 
    401464 
    402 // set localization charset based on the given language 
     465/** 
     466 * Set localization charset based on the given language. 
     467 * This also creates a global property for mbstring usage. 
     468 */ 
    403469function rcmail_set_locale($lang) 
    404470  { 
     
    419485 
    420486 
    421 // auto-select IMAP host based on the posted login information 
     487/** 
     488 * Auto-select IMAP host based on the posted login information 
     489 * 
     490 * @return string Selected IMAP host 
     491 */ 
    422492function rcmail_autoselect_host() 
    423493  { 
     
    447517 
    448518 
    449 // perfom login to the IMAP server and to the webmail service 
     519/** 
     520 * Perfom login to the IMAP server and to the webmail service. 
     521 * This will also create a new user entry if auto_create_user is configured. 
     522 * 
     523 * @param string IMAP user name 
     524 * @param string IMAP password 
     525 * @param string IMAP host 
     526 * @return boolean True on success, False on failure 
     527 */ 
    450528function rcmail_login($user, $pass, $host=NULL) 
    451529  { 
     
    576654 
    577655 
    578 // create new entry in users and identities table 
     656/** 
     657 * Create new entry in users and identities table 
     658 * 
     659 * @param string User name 
     660 * @param string IMAP host 
     661 * @return mixed New user ID or False on failure 
     662 */ 
    579663function rcmail_create_user($user, $host) 
    580664{ 
     
    647731 
    648732 
    649 // load virtuser table in array 
     733/** 
     734 * Load virtuser table in array 
     735 * 
     736 * @return array Virtuser table entries 
     737 */ 
    650738function rcmail_getvirtualfile() 
    651739  { 
     
    660748 
    661749 
    662 // find matches of the given pattern in virtuser table 
     750/** 
     751 * Find matches of the given pattern in virtuser table 
     752 *  
     753 * @param string Regular expression to search for 
     754 * @return array Matching entries 
     755 */ 
    663756function rcmail_findinvirtual($pattern) 
    664757  { 
     
    683776 
    684777 
    685 // resolve username with virtuser table 
     778/** 
     779 * Resolve username using a virtuser table 
     780 * 
     781 * @param string E-mail address to resolve 
     782 * @return string Resolved IMAP username 
     783 */ 
    686784function rcmail_email2user($email) 
    687785  { 
     
    704802 
    705803 
    706 // resolve e-mail address with virtuser table 
     804/** 
     805 * Resolve e-mail address from virtuser table 
     806 * 
     807 * @param string User name 
     808 * @return string Resolved e-mail address 
     809 */ 
    707810function rcmail_user2email($user) 
    708811  { 
     
    725828 
    726829 
     830/** 
     831 * Write the given user prefs to the user's record 
     832 * 
     833 * @param mixed User prefs to save 
     834 * @return boolean True on success, False on failure 
     835 */ 
    727836function rcmail_save_user_prefs($a_user_prefs) 
    728837  { 
     
    748857 
    749858 
    750 // overwrite action variable   
     859/** 
     860 * Overwrite action variable 
     861 * 
     862 * @param string New action value 
     863 */ 
    751864function rcmail_overwrite_action($action) 
    752865  { 
     
    790903 
    791904 
    792 // encrypt IMAP password using DES encryption 
     905/** 
     906 * Encrypt IMAP password using DES encryption 
     907 * 
     908 * @param string Password to encrypt 
     909 * @return string Encryprted string 
     910 */ 
    793911function encrypt_passwd($pass) 
    794912  { 
     
    798916 
    799917 
    800 // decrypt IMAP password using DES encryption 
     918/** 
     919 * Decrypt IMAP password using DES encryption 
     920 * 
     921 * @param string Encrypted password 
     922 * @return string Plain password 
     923 */ 
    801924function decrypt_passwd($cypher) 
    802925  { 
     
    806929 
    807930 
    808 // return a 24 byte key for the DES encryption 
     931/** 
     932 * Return a 24 byte key for the DES encryption 
     933 * 
     934 * @return string DES encryption key 
     935 */ 
    809936function get_des_key() 
    810937  { 
     
    822949 
    823950 
    824 // read directory program/localization/ and return a list of available languages 
     951/** 
     952 * Read directory program/localization and return a list of available languages 
     953 * 
     954 * @return array List of available localizations 
     955 */ 
    825956function rcube_list_languages() 
    826957  { 
     
    849980 
    850981 
    851 // add a localized label to the client environment 
     982/** 
     983 * Add a localized label to the client environment 
     984 */ 
    852985function rcube_add_label() 
    853986  { 
     
    860993 
    861994 
    862 // remove temp files older than two day 
     995/** 
     996 * Garbage collector function for temp files. 
     997 * Remove temp files older than two days 
     998 */ 
    863999function rcmail_temp_gc() 
    8641000  { 
     
    8821018 
    8831019 
    884 // remove all expired message cache records 
     1020/** 
     1021 * Garbage collector for cache entries. 
     1022 * Remove all expired message cache records 
     1023 */ 
    8851024function rcmail_message_cache_gc() 
    8861025  { 
     
    10551194   
    10561195/** 
    1057  * Quote a given string. Alias function for rep_specialchars_output 
    1058  * @see rep_specialchars_output 
     1196 * Quote a given string. 
     1197 * Shortcut function for rep_specialchars_output 
     1198 * 
     1199 * @return string HTML-quoted string 
     1200 * @see rep_specialchars_output() 
    10591201 */ 
    10601202function Q($str, $mode='strict', $newlines=TRUE) 
     
    10641206 
    10651207/** 
    1066  * Quote a given string. Alias function for rep_specialchars_output 
    1067  * @see rep_specialchars_output 
     1208 * Quote a given string for javascript output. 
     1209 * Shortcut function for rep_specialchars_output 
     1210 *  
     1211 * @return string JS-quoted string 
     1212 * @see rep_specialchars_output() 
    10681213 */ 
    10691214function JQ($str) 
     
    11171262  } 
    11181263 
     1264 
    11191265/** 
    11201266 * Remove single and double quotes from given string 
     1267 * 
     1268 * @param string Input value 
     1269 * @return string Dequoted string 
    11211270 */ 
    11221271function strip_quotes($str) 
     
    11251274} 
    11261275 
     1276 
    11271277/** 
    11281278 * Remove new lines characters from given string 
     1279 * 
     1280 * @param string Input value 
     1281 * @return string Stripped string 
    11291282 */ 
    11301283function strip_newlines($str) 
     
    11341287 
    11351288 
    1136 // return boolean if a specific template exists 
     1289/** 
     1290 * Check if a specific template exists 
     1291 * 
     1292 * @param string Template name 
     1293 * @return boolean True if template exists 
     1294 */ 
    11371295function template_exists($name) 
    11381296  { 
     
    11451303 
    11461304 
    1147 // Wrapper for rcmail_template::parse() 
    1148 // @deprecated 
     1305/** 
     1306 * Wrapper for rcmail_template::parse() 
     1307 * @deprecated 
     1308 */ 
    11491309function parse_template($name='main', $exit=true) 
    11501310  { 
     
    11531313 
    11541314 
    1155  
     1315/** 
     1316 * Create a HTML table based on the given data 
     1317 * 
     1318 * @param  array  Named table attributes 
     1319 * @param  mixed  Table row data. Either a two-dimensional array or a valid SQL result set 
     1320 * @param  array  List of cols to show 
     1321 * @param  string Name of the identifier col 
     1322 * @return string HTML table code 
     1323 */ 
    11561324function rcube_table_output($attrib, $table_data, $a_show_cols, $id_col) 
    11571325  { 
     
    12551423 
    12561424 
    1257 // return the mail domain configured for the given host 
     1425/** 
     1426 * Return the mail domain configured for the given host 
     1427 * 
     1428 * @param string IMAP host 
     1429 * @return string Resolved SMTP host 
     1430 */ 
    12581431function rcmail_mail_domain($host) 
    12591432  { 
     
    12731446 
    12741447 
    1275 // compose a valid attribute string for HTML tags 
     1448/** 
     1449 * Compose a valid attribute string for HTML tags 
     1450 * 
     1451 * @param array Named tag attributes 
     1452 * @param array List of allowed attributes 
     1453 * @return string HTML formatted attribute string 
     1454 */ 
    12761455function create_attrib_string($attrib, $allowed_attribs=array('id', 'class', 'style')) 
    12771456  { 
     
    12861465 
    12871466 
    1288 // convert a HTML attribute string attributes to an associative array (name => value) 
     1467/** 
     1468 * Convert a HTML attribute string attributes to an associative array (name => value) 
     1469 * 
     1470 * @param string Input string 
     1471 * @return array Key-value pairs of parsed attributes 
     1472 */ 
    12891473function parse_attrib_string($str) 
    12901474  { 
     
    13011485 
    13021486 
     1487/** 
     1488 * Convert the given date to a human readable form 
     1489 * This uses the date formatting properties from config 
     1490 * 
     1491 * @param mixed Date representation (string or timestamp) 
     1492 * @param string Date format to use 
     1493 * @return string Formatted date string 
     1494 */ 
    13031495function format_date($date, $format=NULL) 
    13041496  { 
     
    13721564 
    13731565 
     1566/** 
     1567 * Compose a valid representaion of name and e-mail address 
     1568 * 
     1569 * @param string E-mail address 
     1570 * @param string Person name 
     1571 * @return string Formatted string 
     1572 */ 
    13741573function format_email_recipient($email, $name='') 
    13751574  { 
     
    13801579  } 
    13811580 
    1382  
    1383  
    1384 // ************** functions delivering gui objects ************** 
    1385  
    1386  
    1387  
    1388 function rcmail_message_container($attrib) 
    1389   { 
    1390   global $OUTPUT; 
    1391  
    1392   if (!$attrib['id']) 
    1393     $attrib['id'] = 'rcmMessageContainer'; 
    1394  
    1395   // allow the following attributes to be added to the <table> tag 
    1396   $attrib_str = create_attrib_string($attrib, array('style', 'class', 'id')); 
    1397   $out = '<div' . $attrib_str . "></div>"; 
    1398    
    1399   $OUTPUT->add_gui_object('message', $attrib['id']); 
    1400    
    1401   return $out; 
    1402   } 
    1403  
    1404  
    1405 // return the IMAP username of the current session 
    1406 function rcmail_current_username($attrib) 
    1407   { 
    1408   global $DB; 
    1409   static $s_username; 
    1410  
    1411   // alread fetched   
    1412   if (!empty($s_username)) 
    1413     return $s_username; 
    1414  
    1415   // get e-mail address form default identity 
    1416   $sql_result = $DB->query("SELECT email AS mailto 
    1417                             FROM ".get_table_name('identities')." 
    1418                             WHERE  user_id=? 
    1419                             AND    standard=1 
    1420                             AND    del<>1", 
    1421                             $_SESSION['user_id']); 
    1422                                     
    1423   if ($DB->num_rows($sql_result)) 
    1424     { 
    1425     $sql_arr = $DB->fetch_assoc($sql_result); 
    1426     $s_username = $sql_arr['mailto']; 
    1427     } 
    1428   else if (strstr($_SESSION['username'], '@')) 
    1429     $s_username = $_SESSION['username']; 
    1430   else 
    1431     $s_username = $_SESSION['username'].'@'.$_SESSION['imap_host']; 
    1432  
    1433   return $s_username; 
    1434   } 
    1435  
    1436  
    1437 // return code for the webmail login form 
    1438 function rcmail_login_form($attrib) 
    1439   { 
    1440   global $CONFIG, $OUTPUT, $SESS_HIDDEN_FIELD; 
    1441    
    1442   $labels = array(); 
    1443   $labels['user'] = rcube_label('username'); 
    1444   $labels['pass'] = rcube_label('password'); 
    1445   $labels['host'] = rcube_label('server'); 
    1446    
    1447   $input_user = new textfield(array('name' => '_user', 'id' => 'rcmloginuser', 'size' => 30, 'autocomplete' => 'off')); 
    1448   $input_pass = new passwordfield(array('name' => '_pass', 'id' => 'rcmloginpwd', 'size' => 30)); 
    1449   $input_action = new hiddenfield(array('name' => '_action', 'value' => 'login')); 
    1450      
    1451   $fields = array(); 
    1452   $fields['user'] = $input_user->show(get_input_value('_user', RCUBE_INPUT_POST)); 
    1453   $fields['pass'] = $input_pass->show(); 
    1454   $fields['action'] = $input_action->show(); 
    1455    
    1456   if (is_array($CONFIG['default_host'])) 
    1457     { 
    1458     $select_host = new select(array('name' => '_host', 'id' => 'rcmloginhost')); 
    1459      
    1460     foreach ($CONFIG['default_host'] as $key => $value) 
    1461     { 
    1462       if (!is_array($value)) 
    1463         $select_host->add($value, (is_numeric($key) ? $value : $key)); 
    1464       else 
    1465         { 
    1466         unset($select_host); 
    1467         break; 
    1468         } 
    1469     } 
    1470        
    1471     $fields['host'] = isset($select_host) ? $select_host->show($_POST['_host']) : null; 
    1472     } 
    1473   else if (!strlen($CONFIG['default_host'])) 
    1474     { 
    1475     $input_host = new textfield(array('name' => '_host', 'id' => 'rcmloginhost', 'size' => 30)); 
    1476     $fields['host'] = $input_host->show($_POST['_host']); 
    1477     } 
    1478  
    1479   $form_name = strlen($attrib['form']) ? $attrib['form'] : 'form'; 
    1480   $form_start = !strlen($attrib['form']) ? '<form name="form" action="./" method="post">' : ''; 
    1481   $form_end = !strlen($attrib['form']) ? '</form>' : ''; 
    1482    
    1483   if ($fields['host']) 
    1484     $form_host = <<<EOF 
    1485      
    1486 </tr><tr> 
    1487  
    1488 <td class="title"><label for="rcmloginhost">$labels[host]</label></td> 
    1489 <td>$fields[host]</td> 
    1490  
    1491 EOF; 
    1492  
    1493   $OUTPUT->add_gui_object('loginform', $form_name); 
    1494    
    1495   $out = <<<EOF 
    1496 $form_start 
    1497 $SESS_HIDDEN_FIELD 
    1498 $fields[action] 
    1499 <table><tr> 
    1500  
    1501 <td class="title"><label for="rcmloginuser">$labels[user]</label></td> 
    1502 <td>$fields[user]</td> 
    1503  
    1504 </tr><tr> 
    1505  
    1506 <td class="title"><label for="rcmloginpwd">$labels[pass]</label></td> 
    1507 <td>$fields[pass]</td> 
    1508 $form_host 
    1509 </tr></table> 
    1510 $form_end 
    1511 EOF; 
    1512  
    1513   return $out; 
    1514   } 
    1515  
    1516  
    1517 function rcmail_charset_selector($attrib) 
    1518   { 
    1519   global $OUTPUT; 
    1520    
    1521   // pass the following attributes to the form class 
    1522   $field_attrib = array('name' => '_charset'); 
    1523   foreach ($attrib as $attr => $value) 
    1524     if (in_array($attr, array('id', 'class', 'style', 'size', 'tabindex'))) 
    1525       $field_attrib[$attr] = $value; 
    1526        
    1527   $charsets = array( 
    1528     'US-ASCII'     => 'ASCII (English)', 
    1529     'EUC-JP'       => 'EUC-JP (Japanese)', 
    1530     'EUC-KR'       => 'EUC-KR (Korean)', 
    1531     'BIG5'         => 'BIG5 (Chinese)', 
    1532     'GB2312'       => 'GB2312 (Chinese)', 
    1533     'ISO-2022-JP'  => 'ISO-2022-JP (Japanese)', 
    1534     'ISO-8859-1'   => 'ISO-8859-1 (Latin-1)', 
    1535     'ISO-8859-2'   => 'ISO-8895-2 (Central European)', 
    1536     'ISO-8859-7'   => 'ISO-8859-7 (Greek)', 
    1537     'ISO-8859-9'   => 'ISO-8859-9 (Turkish)', 
    1538     'Windows-1251' => 'Windows-1251 (Cyrillic)', 
    1539     'Windows-1252' => 'Windows-1252 (Western)', 
    1540     'Windows-1255' => 'Windows-1255 (Hebrew)', 
    1541     'Windows-1256' => 'Windows-1256 (Arabic)', 
    1542     'Windows-1257' => 'Windows-1257 (Baltic)', 
    1543     'UTF-8'        => 'UTF-8' 
    1544     ); 
    1545  
    1546   $select = new select($field_attrib); 
    1547   $select->add(array_values($charsets), array_keys($charsets)); 
    1548    
    1549   $set = $_POST['_charset'] ? $_POST['_charset'] : $OUTPUT->get_charset(); 
    1550   return $select->show($set); 
    1551   } 
    1552  
    1553  
    1554 // return code for search function 
    1555 function rcmail_search_form($attrib) 
    1556   { 
    1557   global $OUTPUT; 
    1558  
    1559   // add some labels to client 
    1560   rcube_add_label('searching'); 
    1561  
    1562   $attrib['name'] = '_q'; 
    1563  
    1564   if (empty($attrib['id'])) 
    1565     $attrib['id'] = 'rcmqsearchbox'; 
    1566  
    1567   $input_q = new textfield($attrib); 
    1568   $out = $input_q->show(); 
    1569  
    1570   $OUTPUT->add_gui_object('qsearchbox', $attrib['id']); 
    1571  
    1572   // add form tag around text field 
    1573   if (empty($attrib['form'])) 
    1574     $out = sprintf( 
    1575       '<form name="rcmqsearchform" action="./" '. 
    1576       'onsubmit="%s.command(\'search\');return false" style="display:inline;">%s</form>', 
    1577       JS_OBJECT_NAME, 
    1578       $out); 
    1579  
    1580   return $out; 
    1581   }  
    15821581 
    15831582 
     
    16381637 
    16391638 
     1639/** 
     1640 * @access private 
     1641 */ 
    16401642function rcube_timer() 
    16411643  { 
     
    16451647   
    16461648 
     1649/** 
     1650 * @access private 
     1651 */ 
    16471652function rcube_print_time($timer, $label='Timer') 
    16481653  { 
     
    16601665 
    16611666 
    1662 // return the mailboxlist in HTML 
     1667/** 
     1668 * Return the mailboxlist in HTML 
     1669 * 
     1670 * @param array Named parameters 
     1671 * @return string HTML code for the gui object 
     1672 */ 
    16631673function rcmail_mailbox_list($attrib) 
    16641674  { 
     
    17301740 
    17311741 
    1732 // create a hierarchical array of the mailbox list 
     1742/** 
     1743 * Create a hierarchical array of the mailbox list 
     1744 * @access private 
     1745 */ 
    17331746function rcmail_build_folder_tree(&$arrFolders, $folder, $delm='/', $path='') 
    17341747  { 
     
    17591772   
    17601773 
    1761 // return html for a structured list <ul> for the mailbox tree 
     1774/** 
     1775 * Return html for a structured list &lt;ul&gt; for the mailbox tree 
     1776 * @access private 
     1777 */ 
    17621778function rcmail_render_folder_tree_html(&$arrFolders, &$special, &$mbox_name, $maxlength, $nestLevel=0) 
    17631779  { 
     
    18401856 
    18411857 
    1842 // return html for a flat list <select> for the mailbox tree 
     1858/** 
     1859 * Return html for a flat list <select> for the mailbox tree 
     1860 * @access private 
     1861 */ 
    18431862function rcmail_render_folder_tree_select(&$arrFolders, &$special, &$mbox_name, $maxlength, $nestLevel=0) 
    18441863  { 
Note: See TracChangeset for help on using the changeset viewer.