Don't use regular expressions when you don't need to
[squirrelmail.git] / functions / strings.php
index 792c0d0fb46f6af3a2f230fcd4216107a358c62a..08f1930c081c61fc3985194999fe87031c2921a9 100644 (file)
@@ -3,45 +3,24 @@
 /**
  * strings.php
  *
- * Copyright (c) 1999-2004 The SquirrelMail Project Team
- * Licensed under the GNU GPL. For full terms see the file COPYING.
- *
  * This code provides various string manipulation functions that are
- * used by the rest of the Squirrelmail code.
+ * used by the rest of the SquirrelMail code.
  *
+ * @copyright 1999-2011 The SquirrelMail Project Team
+ * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  * @version $Id$
  * @package squirrelmail
  */
 
-/**
- * SquirrelMail version number -- DO NOT CHANGE
- */
-global $version;
-$version = '1.5.1 [CVS]';
-
-/**
- * SquirrelMail internal version number -- DO NOT CHANGE
- * $sm_internal_version = array (release, major, minor)
- */
-global $SQM_INTERNAL_VERSION;
-$SQM_INTERNAL_VERSION = array(1,5,1);
-
-/**
- * There can be a circular issue with includes, where the $version string is
- * referenced by the include of global.php, etc. before it's defined.
- * For that reason, bring in global.php AFTER we define the version strings.
- */
-require_once(SM_PATH . 'functions/global.php');
-
 /**
  * Appends citation markers to the string.
  * Also appends a trailing space.
  *
  * @author Justus Pendleton
- *
- * @param string str The string to append to
- * @param int citeLevel the number of markers to append
+ * @param string $str The string to append to
+ * @param int $citeLevel the number of markers to append
  * @return null
+ * @since 1.5.1
  */
 function sqMakeCite (&$str, $citeLevel) {
     for ($i = 0; $i < $citeLevel; $i++) {
@@ -57,11 +36,11 @@ function sqMakeCite (&$str, $citeLevel) {
  * markers to the newline as necessary.
  *
  * @author Justus Pendleton
- *
- * @param string str the string to make a newline in
- * @param int citeLevel the citation level the newline is at
- * @param int column starting column of the newline
+ * @param string $str the string to make a newline in
+ * @param int $citeLevel the citation level the newline is at
+ * @param int $column starting column of the newline
  * @return null
+ * @since 1.5.1
  */
 function sqMakeNewLine (&$str, $citeLevel, &$column) {
     $str .= "\n";
@@ -77,8 +56,6 @@ function sqMakeNewLine (&$str, $citeLevel, &$column) {
 /**
  * Checks for spaces in strings - only used if PHP doesn't have native ctype support
  *
- * @author Tomas Kuliavas
- *
  * You might be able to rewrite the function by adding short evaluation form.
  *
  * possible problems:
@@ -94,13 +71,14 @@ function sqMakeNewLine (&$str, $citeLevel, &$column) {
  *
  * @param string $string tested string
  * @return bool true when only whitespace symbols are present in test string
+ * @since 1.5.1
  */
 function sm_ctype_space($string) {
-  if ( preg_match('/^[\x09-\x0D]|^\x20/', $string) || $string=='') {
-    return true;
-  } else {
-    return false;
-  }
+    if ( preg_match('/^[\x09-\x0D]|^\x20/', $string) || $string=='') {
+        return true;
+    } else {
+        return false;
+    }
 }
 
 /**
@@ -110,10 +88,10 @@ function sm_ctype_space($string) {
  * bit smarter and when and how to wrap.
  *
  * @author Justus Pendleton
- *
- * @param string body the entire body of text
- * @param int wrap the maximum line length
+ * @param string $body the entire body of text
+ * @param int $wrap the maximum line length
  * @return string the wrapped text
+ * @since 1.5.1
  */
 function &sqBodyWrap (&$body, $wrap) {
     //check for ctype support, and fake it if it doesn't exist
@@ -127,7 +105,7 @@ function &sqBodyWrap (&$body, $wrap) {
     $outString = '';
     // current column since the last newline in the outstring
     $outStringCol = 0;
-    $length = strlen($body);
+    $length = sq_strlen($body);
     // where we are in the original string
     $pos = 0;
     // the number of >>> citation markers we are currently at
@@ -139,12 +117,12 @@ function &sqBodyWrap (&$body, $wrap) {
        // we're at the beginning of a line, get the new cite level
        $newCiteLevel = 0;
 
-       while (($pos < $length) && ($body{$pos} == '>')) {
+       while (($pos < $length) && (sq_substr($body,$pos,1) == '>')) {
            $newCiteLevel++;
            $pos++;
 
            // skip over any spaces interleaved among the cite markers
-           while (($pos < $length) && ($body{$pos} == ' ')) {
+           while (($pos < $length) && (sq_substr($body,$pos,1) == ' ')) {
 
                $pos++;
 
@@ -157,8 +135,8 @@ function &sqBodyWrap (&$body, $wrap) {
        // special case: if this is a blank line then maintain it
        // (i.e. try to preserve original paragraph breaks)
        // unless they occur at the very beginning of the text
-       if (($body{$pos} == "\n" ) && (strlen($outString) != 0)) {
-           $outStringLast = $outString{strlen($outString) - 1};
+       if ((sq_substr($body,$pos,1) == "\n" ) && (sq_strlen($outString) != 0)) {
+           $outStringLast = $outString{sq_strlen($outString) - 1};
            if ($outStringLast != "\n") {
                $outString .= "\n";
            }
@@ -192,7 +170,7 @@ function &sqBodyWrap (&$body, $wrap) {
        }
 
        // find the next newline -- we don't want to go further than that
-       $nextNewline = strpos ($body, "\n", $pos);
+       $nextNewline = sq_strpos ($body, "\n", $pos);
        if ($nextNewline === FALSE) {
            $nextNewline = $length;
        }
@@ -201,7 +179,7 @@ function &sqBodyWrap (&$body, $wrap) {
        // will work fine for this.  Maybe revisit this later though
        // (for completeness more than anything else, I think)
        if ($citeLevel == 0) {
-           $outString .= substr ($body, $pos, ($nextNewline - $pos));
+           $outString .= sq_substr ($body, $pos, ($nextNewline - $pos));
            $outStringCol = $nextNewline - $pos;
            if ($nextNewline != $length) {
                sqMakeNewLine ($outString, 0, $outStringCol);
@@ -217,7 +195,7 @@ function &sqBodyWrap (&$body, $wrap) {
        // the next newline
        while ($pos < $nextNewline) {
            // skip over initial spaces
-           while (($pos < $nextNewline) && (ctype_space ($body{$pos}))) {
+           while (($pos < $nextNewline) && (ctype_space (sq_substr($body,$pos,1)))) {
                $pos++;
            }
            // if this is a short line then just append it and continue outer loop
@@ -225,25 +203,24 @@ function &sqBodyWrap (&$body, $wrap) {
                // if this is the final line in the input string then include
                // any trailing newlines
                //      echo substr($body,$pos,$wrap). "<br />";
-               if (($nextNewline + 1 == $length) && ($body{$nextNewline} == "\n")) {
+               if (($nextNewline + 1 == $length) && (sq_substr($body,$nextNewline,1) == "\n")) {
                    $nextNewline++;
                }
 
                // trim trailing spaces
                $lastRealChar = $nextNewline;
-               while (($lastRealChar > $pos && $lastRealChar < $length) && (ctype_space ($body{$lastRealChar}))) {
+               while (($lastRealChar > $pos && $lastRealChar < $length) && (ctype_space (sq_substr($body,$lastRealChar,1)))) {
                    $lastRealChar--;
                }
                // decide if appending the short string is what we want
-               if (($nextNewline < $length && $body{$nextNewline} == "\n") &&
+               if (($nextNewline < $length && sq_substr($body,$nextNewline,1) == "\n") &&
                      isset($lastRealChar)) {
                    $mypos = $pos;
                    //check the first word:
-                   while (($mypos < $length) && ($body{$mypos} == '>')) {
+                   while (($mypos < $length) && (sq_substr($body,$mypos,1) == '>')) {
                        $mypos++;
                        // skip over any spaces interleaved among the cite markers
-                       $oldpos = $mypos;
-                       while (($mypos < $length) && ($body{$mypos} == ' ')) {
+                       while (($mypos < $length) && (sq_substr($body,$mypos,1) == ' ')) {
                            $mypos++;
                        }
                    }
@@ -256,15 +233,15 @@ function &sqBodyWrap (&$body, $wrap) {
                      }
 */
 
-                   $firstword = substr($body,$mypos,strpos($body,' ',$mypos) - $mypos);
+                   $firstword = sq_substr($body,$mypos,sq_strpos($body,' ',$mypos) - $mypos);
                    //if ($dowrap || $ldnspacecnt > 1 || ($firstword && (
                    if (!$smartwrap || $firstword && (
                                         $firstword{0} == '-' ||
                                         $firstword{0} == '+' ||
                                         $firstword{0} == '*' ||
-                                        $firstword{0} == strtoupper($firstword{0}) ||
+                                        sq_substr($firstword,0,1) == sq_strtoupper(sq_substr($firstword,0,1)) ||
                                         strpos($firstword,':'))) {
-                        $outString .= substr($body,$pos,($lastRealChar - $pos+1));
+                        $outString .= sq_substr($body,$pos,($lastRealChar - $pos+1));
                         $outStringCol += ($lastRealChar - $pos);
                         sqMakeNewLine($outString,$citeLevel,$outStringCol);
                         $nextNewline++;
@@ -275,7 +252,7 @@ function &sqBodyWrap (&$body, $wrap) {
 
                }
 
-               $outString .= substr ($body, $pos, ($lastRealChar - $pos + 1));
+               $outString .= sq_substr ($body, $pos, ($lastRealChar - $pos + 1));
                $outStringCol += ($lastRealChar - $pos);
                $pos = $nextNewline + 1;
                continue;
@@ -294,7 +271,7 @@ function &sqBodyWrap (&$body, $wrap) {
 
            // start looking backwards for whitespace to break at.
            $breakPoint = $eol;
-           while (($breakPoint > $pos) && (! ctype_space ($body{$breakPoint}))) {
+           while (($breakPoint > $pos) && (! ctype_space (sq_substr($body,$breakPoint,1)))) {
                $breakPoint--;
            }
 
@@ -327,13 +304,13 @@ function &sqBodyWrap (&$body, $wrap) {
            }
 
            // skip newlines or whitespace at the beginning of the string
-           $substring = substr ($body, $pos, ($breakPoint - $pos));
+           $substring = sq_substr ($body, $pos, ($breakPoint - $pos));
            $substring = rtrim ($substring); // do rtrim and ctype_space have the same ideas about whitespace?
            $outString .= $substring;
-           $outStringCol += strlen ($substring);
+           $outStringCol += sq_strlen ($substring);
            // advance past the whitespace which caused the wrap
            $pos = $breakPoint;
-           while (($pos < $length) && (ctype_space ($body{$pos}))) {
+           while (($pos < $length) && (ctype_space (sq_substr($body,$pos,1)))) {
                $pos++;
            }
            if ($pos < $length) {
@@ -351,16 +328,19 @@ function &sqBodyWrap (&$body, $wrap) {
  * Has a problem with special HTML characters, so call this before
  * you do character translation.
  *
- * Specifically, &#039 comes up as 5 characters instead of 1.
+ * Specifically, &amp;#039; comes up as 5 characters instead of 1.
  * This should not add newlines to the end of lines.
  *
- * @param string line the line of text to wrap, by ref
- * @param int wrap the maximum line lenth
+ * @param string $line the line of text to wrap, by ref
+ * @param int $wrap the maximum line lenth
+ * @param string $charset name of charset used in $line string. Available since v.1.5.1.
  * @return void
+ * @since 1.0
  */
-function sqWordWrap(&$line, $wrap) {
+function sqWordWrap(&$line, $wrap, $charset='') {
     global $languages, $squirrelmail_language;
 
+    // Use custom wrapping function, if translation provides it
     if (isset($languages[$squirrelmail_language]['XTRA_CODE']) &&
         function_exists($languages[$squirrelmail_language]['XTRA_CODE'] . '_wordwrap')) {
         if (mb_detect_encoding($line) != 'ASCII') {
@@ -369,12 +349,12 @@ function sqWordWrap(&$line, $wrap) {
         }
     }
 
-    ereg("^([\t >]*)([^\t >].*)?$", $line, $regs);
+    preg_match('/^([\t >]*)([^\t >].*)?$/', $line, $regs);
     $beginning_spaces = $regs[1];
     if (isset($regs[2])) {
         $words = explode(' ', $regs[2]);
     } else {
-        $words = '';
+        $words = array();
     }
 
     $i = 0;
@@ -383,9 +363,9 @@ function sqWordWrap(&$line, $wrap) {
     while ($i < count($words)) {
         /* Force one word to be on a line (minimum) */
         $line .= $words[$i];
-        $line_len = strlen($beginning_spaces) + strlen($words[$i]) + 2;
+        $line_len = strlen($beginning_spaces) + sq_strlen($words[$i],$charset) + 2;
         if (isset($words[$i + 1]))
-            $line_len += strlen($words[$i + 1]);
+            $line_len += sq_strlen($words[$i + 1],$charset);
         $i ++;
 
         /* Add more words (as long as they fit) */
@@ -393,7 +373,7 @@ function sqWordWrap(&$line, $wrap) {
             $line .= ' ' . $words[$i];
             $i++;
             if (isset($words[$i]))
-                $line_len += strlen($words[$i]) + 1;
+                $line_len += sq_strlen($words[$i],$charset) + 1;
             else
                 $line_len += 1;
         }
@@ -412,8 +392,9 @@ function sqWordWrap(&$line, $wrap) {
 
 /**
  * Does the opposite of sqWordWrap()
- * @param string body the text to un-wordwrap
+ * @param string $body the text to un-wordwrap
  * @return void
+ * @since 1.0
  */
 function sqUnWordWrap(&$body) {
     global $squirrelmail_language;
@@ -457,6 +438,7 @@ function sqUnWordWrap(&$body) {
  * @param string haystack full mailbox name to search
  * @param string needle the mailbox separator character
  * @return string the last part of the mailbox name
+ * @since 1.0
  */
 function readShortMailboxName($haystack, $needle) {
 
@@ -472,50 +454,24 @@ function readShortMailboxName($haystack, $needle) {
     return( $elem );
 }
 
-/**
- * php_self
- *
- * Creates an URL for the page calling this function, using either the PHP global
- * REQUEST_URI, or the PHP global PHP_SELF with QUERY_STRING added.
- *
- * @return string the complete url for this page
- */
-function php_self () {
-    if ( sqgetGlobalVar('REQUEST_URI', $req_uri, SQ_SERVER) && !empty($req_uri) ) {
-      return $req_uri;
-    }
-
-    if ( sqgetGlobalVar('PHP_SELF', $php_self, SQ_SERVER) && !empty($php_self) ) {
-
-      // need to add query string to end of PHP_SELF to match REQUEST_URI
-      //
-      if ( sqgetGlobalVar('QUERY_STRING', $query_string, SQ_SERVER) && !empty($query_string) ) {
-         $php_self .= '?' . $query_string;
-      }
-
-      return $php_self;
-    }
-
-    return '';
-}
-
 
 /**
  * get_location
  *
  * Determines the location to forward to, relative to your server.
  * This is used in HTTP Location: redirects.
- * If this doesnt work correctly for you (although it should), you can
- * remove all this code except the last two lines, and have it return
- * the right URL for your site, something like:
  *
- *   http://www.example.com/squirrelmail/
+ * If set, it uses $config_location_base as the first part of the URL,
+ * specifically, the protocol, hostname and port parts. The path is
+ * always autodetected.
  *
  * @return string the base url for this SquirrelMail installation
+ * @since 1.0
  */
 function get_location () {
 
-    global $imap_server_type;
+    global $imap_server_type, $config_location_base,
+           $is_secure_connection, $sq_ignore_http_x_forwarded_headers;
 
     /* Get the path, handle virtual directories */
     if(strpos(php_self(), '?')) {
@@ -524,55 +480,93 @@ function get_location () {
         $path = php_self();
     }
     $path = substr($path, 0, strrpos($path, '/'));
+
+    // proto+host+port are already set in config:
+    if ( !empty($config_location_base) ) {
+        return $config_location_base . $path ;
+    }
+    // we computed it before, get it from the session:
     if ( sqgetGlobalVar('sq_base_url', $full_url, SQ_SESSION) ) {
       return $full_url . $path;
     }
+    // else: autodetect
 
     /* Check if this is a HTTPS or regular HTTP request. */
     $proto = 'http://';
-
-    /*
-     * If you have 'SSLOptions +StdEnvVars' in your apache config
-     *     OR if you have HTTPS=on in your HTTP_SERVER_VARS
-     *     OR if you are on port 443
-     */
-    $getEnvVar = getenv('HTTPS');
-    if ((isset($getEnvVar) && !strcasecmp($getEnvVar, 'on')) ||
-        (sqgetGlobalVar('HTTPS', $https_on, SQ_SERVER) && !strcasecmp($https_on, 'on')) ||
-        (sqgetGlobalVar('SERVER_PORT', $server_port, SQ_SERVER) &&  $server_port == 443)) {
+    if ($is_secure_connection)
         $proto = 'https://';
-    }
 
     /* Get the hostname from the Host header or server config. */
-    if ( !sqgetGlobalVar('HTTP_HOST', $host, SQ_SERVER) || empty($host) ) {
-      if ( !sqgetGlobalVar('SERVER_NAME', $host, SQ_SERVER) || empty($host) ) {
-        $host = '';
-      }
+    if ($sq_ignore_http_x_forwarded_headers
+     || !sqgetGlobalVar('HTTP_X_FORWARDED_HOST', $host, SQ_SERVER)
+     || empty($host)) {
+        if ( !sqgetGlobalVar('HTTP_HOST', $host, SQ_SERVER) || empty($host) ) {
+            if ( !sqgetGlobalVar('SERVER_NAME', $host, SQ_SERVER) || empty($host) ) {
+                $host = '';
+            }
+        }
     }
 
     $port = '';
     if (! strstr($host, ':')) {
+        // Note: HTTP_X_FORWARDED_PROTO could be sent from the client and
+        //       therefore possibly spoofed/hackable.  Thus, SquirrelMail
+        //       ignores such headers by default.  The administrator
+        //       can tell SM to use such header values by setting
+        //       $sq_ignore_http_x_forwarded_headers to boolean FALSE
+        //       in config/config.php or by using config/conf.pl.
+        global $sq_ignore_http_x_forwarded_headers;
+        if ($sq_ignore_http_x_forwarded_headers
+         || !sqgetGlobalVar('HTTP_X_FORWARDED_PROTO', $forwarded_proto, SQ_SERVER))
+            $forwarded_proto = '';
         if (sqgetGlobalVar('SERVER_PORT', $server_port, SQ_SERVER)) {
             if (($server_port != 80 && $proto == 'http://') ||
-                ($server_port != 443 && $proto == 'https://')) {
+                ($server_port != 443 && $proto == 'https://' &&
+                 strcasecmp($forwarded_proto, 'https') !== 0)) {
                 $port = sprintf(':%d', $server_port);
             }
         }
     }
 
-   /* this is a workaround for the weird macosx caching that
-      causes Apache to return 16080 as the port number, which causes
-      SM to bail */
+    /* this is a workaround for the weird macosx caching that
+     * causes Apache to return 16080 as the port number, which causes
+     * SM to bail */
 
-   if ($imap_server_type == 'macosx' && $port == ':16080') {
+    if ($imap_server_type == 'macosx' && $port == ':16080') {
         $port = '';
-   }
+    }
+
+    /* Fallback is to omit the server name and use a relative */
+    /* URI, although this is not RFC 2616 compliant.          */
+    $full_url = ($host ? $proto . $host . $port : '');
+    sqsession_register($full_url, 'sq_base_url');
+    return $full_url . $path;
+}
+
+
+/**
+ * Get Message List URI
+ *
+ * @param string $mailbox      Current mailbox name (unencoded/raw)
+ * @param string $startMessage The mailbox page offset
+ * @param string $what         Any current search parameters (OPTIONAL; 
+ *                             default empty string)
+ *
+ * @return string The message list URI
+ *
+ * @since 1.5.2
+ *
+ */
+function get_message_list_uri($mailbox, $startMessage, $what='') {
 
-   /* Fallback is to omit the server name and use a relative */
-   /* URI, although this is not RFC 2616 compliant.          */
-   $full_url = ($host ? $proto . $host . $port : '');
-   sqsession_register($full_url, 'sq_base_url');
-   return $full_url . $path;
+    global $base_uri;
+
+    $urlMailbox = urlencode($mailbox);
+
+    $list_xtra = "?where=read_body.php&what=$what&mailbox=" . $urlMailbox.
+                 "&startMessage=$startMessage";
+
+    return $base_uri .'src/right_main.php'. $list_xtra;
 }
 
 
@@ -583,12 +577,23 @@ function get_location () {
  * stored in a cookie. The encryption key is generated by
  * OneTimePadCreate();
  *
- * @param string string the (password)string to encrypt
- * @param string epad the encryption key
+ * @param string $string the (password)string to encrypt
+ * @param string $epad the encryption key
  * @return string the base64-encoded encrypted password
+ * @since 1.0
  */
 function OneTimePadEncrypt ($string, $epad) {
     $pad = base64_decode($epad);
+
+    if (strlen($pad)>0) {
+        // make sure that pad is longer than string
+        while (strlen($string)>strlen($pad)) {
+            $pad.=$pad;
+        }
+    } else {
+        // FIXME: what should we do when $epad is not base64 encoded or empty.
+    }
+
     $encrypted = '';
     for ($i = 0; $i < strlen ($string); $i++) {
         $encrypted .= chr (ord($string[$i]) ^ ord($pad[$i]));
@@ -603,12 +608,23 @@ function OneTimePadEncrypt ($string, $epad) {
  * Decrypts a password from the cookie, encrypted by OneTimePadEncrypt.
  * This uses the encryption key that is stored in the session.
  *
- * @param string string the string to decrypt
- * @param string epad the encryption key from the session
+ * @param string $string the string to decrypt
+ * @param string $epad the encryption key from the session
  * @return string the decrypted password
+ * @since 1.0
  */
 function OneTimePadDecrypt ($string, $epad) {
     $pad = base64_decode($epad);
+
+    if (strlen($pad)>0) {
+        // make sure that pad is longer than string
+        while (strlen($string)>strlen($pad)) {
+            $pad.=$pad;
+        }
+    } else {
+        // FIXME: what should we do when $epad is not base64 encoded or empty.
+    }
+
     $encrypted = base64_decode ($string);
     $decrypted = '';
     for ($i = 0; $i < strlen ($encrypted); $i++) {
@@ -618,93 +634,18 @@ function OneTimePadDecrypt ($string, $epad) {
     return $decrypted;
 }
 
-
-/**
- * Randomizes the mt_rand() function.
- *
- * Toss this in strings or integers and it will seed the generator
- * appropriately. With strings, it is better to get them long.
- * Use md5() to lengthen smaller strings.
- *
- * @param mixed val a value to seed the random number generator
- * @return void
- */
-function sq_mt_seed($Val) {
-    /* if mt_getrandmax() does not return a 2^n - 1 number,
-       this might not work well.  This uses $Max as a bitmask. */
-    $Max = mt_getrandmax();
-
-    if (! is_int($Val)) {
-            $Val = crc32($Val);
-    }
-
-    if ($Val < 0) {
-        $Val *= -1;
-    }
-
-    if ($Val == 0) {
-        return;
-    }
-
-    mt_srand(($Val ^ mt_rand(0, $Max)) & $Max);
-}
-
-
-/**
- * Init random number generator
- *
- * This function initializes the random number generator fairly well.
- * It also only initializes it once, so you don't accidentally get
- * the same 'random' numbers twice in one session.
- *
- * @return void
- */
-function sq_mt_randomize() {
-    static $randomized;
-
-    if ($randomized) {
-        return;
-    }
-
-    /* Global. */
-    sqgetGlobalVar('REMOTE_PORT', $remote_port, SQ_SERVER);
-    sqgetGlobalVar('REMOTE_ADDR', $remote_addr, SQ_SERVER);
-    sq_mt_seed((int)((double) microtime() * 1000000));
-    sq_mt_seed(md5($remote_port . $remote_addr . getmypid()));
-
-    /* getrusage */
-    if (function_exists('getrusage')) {
-        /* Avoid warnings with Win32 */
-        $dat = @getrusage();
-        if (isset($dat) && is_array($dat)) {
-            $Str = '';
-            foreach ($dat as $k => $v)
-                {
-                    $Str .= $k . $v;
-                }
-            sq_mt_seed(md5($Str));
-        }
-    }
-
-    if(sqgetGlobalVar('UNIQUE_ID', $unique_id, SQ_SERVER)) {
-        sq_mt_seed(md5($unique_id));
-    }
-
-    $randomized = 1;
-}
-
 /**
  * Creates encryption key
  *
  * Creates an encryption key for encrypting the password stored in the cookie.
  * The encryption key itself is stored in the session.
  *
- * @param int length optional, length of the string to generate
+ * Pad must be longer or equal to encoded string length in 1.4.4/1.5.0 and older.
+ * @param int $length optional, length of the string to generate
  * @return string the encryption key
+ * @since 1.0
  */
 function OneTimePadCreate ($length=100) {
-    sq_mt_randomize();
-
     $pad = '';
     for ($i = 0; $i < $length; $i++) {
         $pad .= chr(mt_rand(0,255));
@@ -714,18 +655,23 @@ function OneTimePadCreate ($length=100) {
 }
 
 /**
- * Returns a string showing the size of the message/attachment.
- *
- * @param int bytes the filesize in bytes
- * @return string the filesize in human readable format
- */
+  * Returns a string showing a byte size figure in
+  * a more easily digested (readable) format
+  *
+  * @param int $bytes the size in bytes
+  *
+  * @return string The size in human readable format
+  *
+  * @since 1.0
+  *
+  */
 function show_readable_size($bytes) {
     $bytes /= 1024;
-    $type = 'k';
+    $type = _("KiB");
 
     if ($bytes / 1024 > 1) {
         $bytes /= 1024;
-        $type = 'M';
+        $type = _("MiB");
     }
 
     if ($bytes < 10) {
@@ -736,20 +682,22 @@ function show_readable_size($bytes) {
         settype($bytes, 'integer');
     }
 
-    return $bytes . '<small>&nbsp;' . $type . '</small>';
+    global $nbsp;
+    return $bytes . $nbsp . $type;
 }
 
 /**
- * Generates a random string from the caracter set you pass in
+ * Generates a random string from the character set you pass in
  *
- * @param int size the size of the string to generate
- * @param string chars a string containing the characters to use
- * @param int flags a flag to add a specific set to the characters to use:
+ * @param int $size the length of the string to generate
+ * @param string $chars a string containing the characters to use
+ * @param int $flags a flag to add a specific set to the characters to use:
  *     Flags:
  *       1 = add lowercase a-z to $chars
  *       2 = add uppercase A-Z to $chars
  *       4 = add numbers 0-9 to $chars
  * @return string the random string
+ * @since 1.0
  */
 function GenerateRandomString($size, $chars, $flags = 0) {
     if ($flags & 0x1) {
@@ -766,8 +714,6 @@ function GenerateRandomString($size, $chars, $flags = 0) {
         return '';
     }
 
-    sq_mt_randomize(); /* Initialize the random number generator */
-
     $String = '';
     $j = strlen( $chars ) - 1;
     while (strlen($String) < $size) {
@@ -780,33 +726,12 @@ function GenerateRandomString($size, $chars, $flags = 0) {
 /**
  * Escapes special characters for use in IMAP commands.
  *
- * @param string the string to escape
+ * @param string $str the string to escape
  * @return string the escaped string
+ * @since 1.0.3
  */
 function quoteimap($str) {
-    return preg_replace("/([\"\\\\])/", "\\\\$1", $str);
-}
-
-/**
- * Trims array
- *
- * Trims every element in the array, ie. remove the first char of each element
- * @param array array the array to trim
- */
-function TrimArray(&$array) {
-    foreach ($array as $k => $v) {
-        global $$k;
-        if (is_array($$k)) {
-            foreach ($$k as $k2 => $v2) {
-                $$k[$k2] = substr($v2, 1);
-            }
-        } else {
-            $$k = substr($v, 1);
-        }
-
-        /* Re-assign back to array. */
-        $array[$k] = $$k;
-    }
+    return str_replace(array('\\', '"'), array('\\\\', '\\"'), $str);
 }
 
 /**
@@ -814,68 +739,56 @@ function TrimArray(&$array) {
  *
  * Returns a link to the compose-page, taking in consideration
  * the compose_in_new and javascript settings.
- * @param string url the URL to the compose page
- * @param string text the link text, default "Compose"
+ *
+ * @param string $url       The URL to the compose page
+ * @param string $text      The link text, default "Compose"
+ * @param string $target    URL target, if any (since 1.4.3)
+ * @param string $accesskey The access key to be used, if any
+ *
  * @return string a link to the compose page
+ *
+ * @since 1.4.2
  */
-function makeComposeLink($url, $text = null, $target='')
-{
-    global $compose_new_win,$javascript_on;
+function makeComposeLink($url, $text = null, $target='', $accesskey='NONE') {
+    global $compose_new_win, $compose_width, 
+           $compose_height, $oTemplate;
 
     if(!$text) {
         $text = _("Compose");
     }
 
-
     // if not using "compose in new window", make
     // regular link and be done with it
     if($compose_new_win != '1') {
-        return makeInternalLink($url, $text, $target);
+        return makeInternalLink($url, $text, $target, $accesskey);
     }
 
-
     // build the compose in new window link...
 
 
-    // if javascript is on, use onClick event to handle it
-    if($javascript_on) {
+    // if javascript is on, use onclick event to handle it
+    if(checkForJavascript()) {
         sqgetGlobalVar('base_uri', $base_uri, SQ_SESSION);
-        return '<a href="javascript:void(0)" onclick="comp_in_new(\''.$base_uri.$url.'\')">'. $text.'</a>';
+        $compuri = SM_BASE_URI.$url;
+
+        return create_hyperlink('javascript:void(0)', $text, '',
+                                "comp_in_new('$compuri','$compose_width','$compose_height')",
+                                '', '', '',
+                                ($accesskey == 'NONE'
+                                ? array()
+                                : array('accesskey' => $accesskey)));
     }
 
-
     // otherwise, just open new window using regular HTML
-    return makeInternalLink($url, $text, '_blank');
-
-}
-
-/**
- * Print variable
- *
- * sm_print_r($some_variable, [$some_other_variable [, ...]]);
- *
- * Debugging function - does the same as print_r, but makes sure special
- * characters are converted to htmlentities first.  This will allow
- * values like <some@email.address> to be displayed.
- * The output is wrapped in <<pre>> and <</pre>> tags.
- *
- * @return void
- */
-function sm_print_r() {
-    ob_start();  // Buffer output
-    foreach(func_get_args() as $var) {
-        print_r($var);
-        echo "\n";
-    }
-    $buffer = ob_get_contents(); // Grab the print_r output
-    ob_end_clean();  // Silently discard the output & stop buffering
-    print '<pre>';
-    print htmlentities($buffer);
-    print '</pre>';
+    return makeInternalLink($url, $text, '_blank', $accesskey);
 }
 
 /**
  * version of fwrite which checks for failure
+ * @param resource $fp
+ * @param string $string
+ * @return number of written bytes. false on failure
+ * @since 1.4.3
  */
 function sq_fwrite($fp, $string) {
         // write to file
@@ -906,6 +819,7 @@ function sq_fwrite($fp, $string) {
  *              </ul>
  * @param string $charset charset used for encoding. default to us-ascii, 'auto' uses $default_charset global value.
  * @return array html translation array
+ * @since 1.5.1
  */
 function sq_get_html_translation_table($table,$quote_style=ENT_COMPAT,$charset='us-ascii') {
   global $default_charset;
@@ -955,7 +869,10 @@ function sq_get_html_translation_table($table,$quote_style=ENT_COMPAT,$charset='
  * sq_htmlentities
  *
  * Convert all applicable characters to HTML entities.
- * Minimal php requirement - v.4.0.5
+ * Minimal php requirement - v.4.0.5.
+ *
+ * Function is designed for people that want to use full power of htmlentities() in
+ * i18n environment.
  *
  * @param string $string string that has to be sanitized
  * @param integer $quote_style quote encoding style. Possible values (without quotes):
@@ -966,6 +883,7 @@ function sq_get_html_translation_table($table,$quote_style=ENT_COMPAT,$charset='
  *              </ul>
  * @param string $charset charset used for encoding. defaults to 'us-ascii', 'auto' uses $default_charset global value.
  * @return string sanitized string
+ * @since 1.5.1
  */
 function sq_htmlentities($string,$quote_style=ENT_COMPAT,$charset='us-ascii') {
   // get translation table
@@ -978,12 +896,12 @@ function sq_htmlentities($string,$quote_style=ENT_COMPAT,$charset='us-ascii') {
  * Tests if string contains 8bit symbols.
  *
  * If charset is not set, function defaults to default_charset.
- * $default_charset global must be set correctly if $charset is 
+ * $default_charset global must be set correctly if $charset is
  * not used.
  * @param string $string tested string
  * @param string $charset charset used in a string
  * @return bool true if 8bit symbols are detected
- * @since 1.5.1
+ * @since 1.5.1 and 1.4.4
  */
 function sq_is8bit($string,$charset='') {
     global $default_charset;
@@ -992,7 +910,7 @@ function sq_is8bit($string,$charset='') {
 
     /**
      * Don't use \240 in ranges. Sometimes RH 7.2 doesn't like it.
-     * Don't use \200-\237 for iso-8859-x charsets. This range
+     * Don't use \200-\237 for iso-8859-x charsets. This range
      * stores control symbols in those charsets.
      * Use preg_match instead of ereg in order to avoid problems
      * with mbstring overloading
@@ -1012,18 +930,25 @@ function sq_is8bit($string,$charset='') {
  * in php 5.x. Function does not test all mbstring encodings. Only the ones
  * that might be used in SM translations.
  *
- * Supported arrays are stored in session in order to reduce number of 
+ * Supported strings are stored in session in order to reduce number of
  * mb_internal_encoding function calls.
  *
- * If you want to test all mbstring encodings - fill $list_of_encodings 
+ * If you want to test all mbstring encodings - fill $list_of_encodings
  * array.
- * @return array list of encodings supported by mbstring
- * @since 1.5.1
+ * @return array list of encodings supported by php mbstring extension
+ * @since 1.5.1 and 1.4.6
  */
 function sq_mb_list_encodings() {
     if (! function_exists('mb_internal_encoding'))
         return array();
 
+    // php 5+ function
+    if (function_exists('mb_list_encodings')) {
+        $ret = mb_list_encodings();
+        array_walk($ret,'sq_lowercase_array_vals');
+        return $ret;
+    }
+
     // don't try to test encodings, if they are already stored in session
     if (sqgetGlobalVar('mb_supported_encodings',$mb_supported_encodings,SQ_SESSION))
         return $mb_supported_encodings;
@@ -1048,12 +973,16 @@ function sq_mb_list_encodings() {
         'koi8-u',
         'big5',
         'gb2312',
+        'gb18030',
         'windows-1251',
         'windows-1255',
         'windows-1256',
         'tis-620',
         'iso-2022-jp',
+        'euc-cn',
         'euc-kr',
+        'euc-tw',
+        'uhc',
         'utf7-imap');
 
     $supported_encodings=array();
@@ -1073,5 +1002,654 @@ function sq_mb_list_encodings() {
     return $supported_encodings;
 }
 
-$PHP_SELF = php_self();
-?>
\ No newline at end of file
+/**
+ * Callback function used to lowercase array values.
+ * @param string $val array value
+ * @param mixed $key array key
+ * @since 1.5.1 and 1.4.6
+ */
+function sq_lowercase_array_vals(&$val,$key) {
+    $val = strtolower($val);
+}
+
+
+/**
+ * Function returns number of characters in string.
+ *
+ * Returned number might be different from number of bytes in string,
+ * if $charset is multibyte charset. Detection depends on mbstring
+ * functions. If mbstring does not support tested multibyte charset,
+ * vanilla string length function is used.
+ * @param string $str string
+ * @param string $charset charset
+ * @since 1.5.1 and 1.4.6
+ * @return integer number of characters in string
+ */
+function sq_strlen($str, $charset=null){
+    // default option
+    if (is_null($charset)) return strlen($str);
+
+    // lowercase charset name
+    $charset=strtolower($charset);
+
+    // use automatic charset detection, if function call asks for it
+    if ($charset=='auto') {
+        global $default_charset, $squirrelmail_language;
+        set_my_charset();
+        $charset=$default_charset;
+        if ($squirrelmail_language=='ja_JP') $charset='euc-jp';
+    }
+
+    // Use mbstring only with listed charsets
+    $aList_of_mb_charsets=array('utf-8','big5','gb2312','gb18030','euc-jp','euc-cn','euc-tw','euc-kr');
+
+    // calculate string length according to charset
+    if (in_array($charset,$aList_of_mb_charsets) && in_array($charset,sq_mb_list_encodings())) {
+        $real_length = mb_strlen($str,$charset);
+    } else {
+        // own strlen detection code is removed because missing strpos,
+        // strtoupper and substr implementations break string wrapping.
+        $real_length=strlen($str);
+    }
+    return $real_length;
+}
+
+/**
+ * string padding with multibyte support
+ *
+ * @link http://www.php.net/str_pad
+ * @param string $string original string
+ * @param integer $width padded string width
+ * @param string $pad padding symbols
+ * @param integer $padtype padding type
+ *  (internal php defines, see str_pad() description)
+ * @param string $charset charset used in original string
+ * @return string padded string
+ */
+function sq_str_pad($string, $width, $pad, $padtype, $charset='') {
+
+    $charset = strtolower($charset);
+    $padded_string = '';
+
+    switch ($charset) {
+    case 'utf-8':
+    case 'big5':
+    case 'gb2312':
+    case 'euc-kr':
+        /*
+         * all multibyte charsets try to increase width value by
+         * adding difference between number of bytes and real length
+         */
+        $width = $width - sq_strlen($string,$charset) + strlen($string);
+    default:
+        $padded_string=str_pad($string,$width,$pad,$padtype);
+    }
+    return $padded_string;
+}
+
+/**
+ * Wrapper that is used to switch between vanilla and multibyte substr
+ * functions.
+ * @param string $string
+ * @param integer $start
+ * @param integer $length
+ * @param string $charset
+ * @return string
+ * @since 1.5.1
+ * @link http://www.php.net/substr
+ * @link http://www.php.net/mb_substr
+ */
+function sq_substr($string,$start,$length=NULL,$charset='auto') {
+
+    // if $length is NULL, use the full string length...
+    // we have to do this to mimick the use of substr()
+    // where $length is not given
+    //
+    if (is_null($length))
+        $length = sq_strlen($length);
+
+
+    // use automatic charset detection, if function call asks for it
+    static $charset_auto, $bUse_mb;
+
+    if ($charset=='auto') {
+        if (!isset($charset_auto)) {
+            global $default_charset, $squirrelmail_language;
+            set_my_charset();
+            $charset=$default_charset;
+            if ($squirrelmail_language=='ja_JP') $charset='euc-jp';
+            $charset_auto = $charset;
+        } else {
+            $charset = $charset_auto;
+        }
+    }
+    $charset = strtolower($charset);
+
+    // in_array call is expensive => do it once and use a static var for
+    // storing the results
+    if (!isset($bUse_mb)) {
+        if (in_array($charset,sq_mb_list_encodings())) {
+            $bUse_mb = true;
+        } else {
+            $bUse_mb = false;
+        }
+    }
+
+    if ($bUse_mb) {
+        return mb_substr($string,$start,$length,$charset);
+    }
+    // TODO: add mbstring independent code
+
+    // use vanilla string functions as last option
+    return substr($string,$start,$length);
+}
+
+/**
+  * This is a replacement for PHP's substr_replace() that is
+  * multibyte-aware.
+  *
+  * @param string $string      The string to operate upon
+  * @param string $replacement The string to be inserted
+  * @param int    $start       The offset at which to begin substring replacement
+  * @param int    $length      The number of characters after $start to remove
+  *                            NOTE that if you need to specify a charset but
+  *                            want to achieve normal substr_replace() behavior
+  *                            where $length is not specified, use NULL (OPTIONAL;
+  *                            default from $start to end of string)
+  * @param string $charset     The charset of the given string.  A value of NULL
+  *                            here will force the use of PHP's standard substr().
+  *                            (OPTIONAL; default is "auto", which indicates that
+  *                            the user's current charset should be used).
+  *
+  * @return string The manipulated string
+  *
+  * Of course, you can use more advanced (e.g., negative) values
+  * for $start and $length as needed - see the PHP manual for more
+  * information:  http://www.php.net/manual/function.substr-replace.php
+  *
+  */
+function sq_substr_replace($string, $replacement, $start, $length=NULL,
+                           $charset='auto')
+{
+
+   // NULL charset?  Just use substr_replace()
+   //
+   if (is_null($charset))
+      return is_null($length) ? substr_replace($string, $replacement, $start)
+                              : substr_replace($string, $replacement, $start, $length);
+
+
+   // use current character set?
+   //
+   if ($charset == 'auto')
+   {
+//FIXME: is there any reason why this cannot be a global flag used by all string wrapper functions?
+      static $auto_charset;
+      if (!isset($auto_charset))
+      {
+         global $default_charset;
+//FIXME - do we need this?
+global $squirrelmail_language;
+         set_my_charset();
+         $auto_charset = $default_charset;
+//FIXME - do we need this?
+if ($squirrelmail_language == 'ja_JP') $auto_charset = 'euc-jp';
+      }
+      $charset = $auto_charset;
+   }
+
+
+   // standardize character set name
+   //
+   $charset = strtolower($charset);
+
+
+/* ===== FIXME: this list is not used in 1.5.x, but if we need it, unless this differs between all our string function wrappers, we should store this info in the session
+   // only use mbstring with the following character sets
+   //
+   $sq_substr_replace_mb_charsets = array(
+      'utf-8',
+      'big5',
+      'gb2312',
+      'gb18030',
+      'euc-jp',
+      'euc-cn',
+      'euc-tw',
+      'euc-kr'
+   );
+
+
+   // now we can use our own implementation using
+   // mb_substr() and mb_strlen() if needed
+   //
+   if (in_array($charset, $sq_substr_replace_mb_charsets)
+    && in_array($charset, sq_mb_list_encodings()))
+===== */
+//FIXME: is there any reason why this cannot be a global array used by all string wrapper functions?
+   if (in_array($charset, sq_mb_list_encodings()))
+   {
+
+      $string_length = mb_strlen($string, $charset);
+
+      if ($start < 0)
+         $start = max(0, $string_length + $start);
+
+      else if ($start > $string_length)
+         $start = $string_length;
+
+      if ($length < 0)
+         $length = max(0, $string_length - $start + $length);
+
+      else if (is_null($length) || $length > $string_length)
+         $length = $string_length;
+
+      if ($start + $length > $string_length)
+         $length = $string_length - $start;
+
+      return mb_substr($string, 0, $start, $charset)
+           . $replacement
+           . mb_substr($string,
+                       $start + $length,
+                       $string_length, // FIXME: I can't see why this is needed:  - $start - $length,
+                       $charset);
+
+   }
+
+
+   // else use normal substr_replace()
+   //
+   return is_null($length) ? substr_replace($string, $replacement, $start)
+                           : substr_replace($string, $replacement, $start, $length);
+
+}
+
+/**
+ * Wrapper that is used to switch between vanilla and multibyte strpos
+ * functions.
+ * @param string $haystack
+ * @param mixed $needle
+ * @param integer $offset
+ * @param string $charset
+ * @return string
+ * @since 1.5.1
+ * @link http://www.php.net/strpos
+ * @link http://www.php.net/mb_strpos
+ */
+function sq_strpos($haystack,$needle,$offset,$charset='auto') {
+    // use automatic charset detection, if function call asks for it
+    static $charset_auto, $bUse_mb;
+
+    if ($charset=='auto') {
+        if (!isset($charset_auto)) {
+            global $default_charset, $squirrelmail_language;
+            set_my_charset();
+            $charset=$default_charset;
+            if ($squirrelmail_language=='ja_JP') $charset='euc-jp';
+            $charset_auto = $charset;
+        } else {
+            $charset = $charset_auto;
+        }
+    }
+    $charset = strtolower($charset);
+
+    // in_array call is expensive => do it once and use a static var for
+    // storing the results
+    if (!isset($bUse_mb)) {
+        if (in_array($charset,sq_mb_list_encodings())) {
+            $bUse_mb = true;
+        } else {
+            $bUse_mb = false;
+        }
+    }
+    if ($bUse_mb) {
+        return mb_strpos($haystack,$needle,$offset,$charset);
+    }
+    // TODO: add mbstring independent code
+
+    // use vanilla string functions as last option
+    return strpos($haystack,$needle,$offset);
+}
+
+/**
+ * Wrapper that is used to switch between vanilla and multibyte strtoupper
+ * functions.
+ * @param string $string
+ * @param string $charset
+ * @return string
+ * @since 1.5.1
+ * @link http://www.php.net/strtoupper
+ * @link http://www.php.net/mb_strtoupper
+ */
+function sq_strtoupper($string,$charset='auto') {
+    // use automatic charset detection, if function call asks for it
+    static $charset_auto, $bUse_mb;
+
+    if ($charset=='auto') {
+        if (!isset($charset_auto)) {
+            global $default_charset, $squirrelmail_language;
+            set_my_charset();
+            $charset=$default_charset;
+            if ($squirrelmail_language=='ja_JP') $charset='euc-jp';
+            $charset_auto = $charset;
+        } else {
+            $charset = $charset_auto;
+        }
+    }
+    $charset = strtolower($charset);
+
+    // in_array call is expensive => do it once and use a static var for
+    // storing the results
+    if (!isset($bUse_mb)) {
+        if (function_exists('mb_strtoupper') &&
+            in_array($charset,sq_mb_list_encodings())) {
+            $bUse_mb = true;
+        } else {
+            $bUse_mb = false;
+        }
+    }
+
+    if ($bUse_mb) {
+        return mb_strtoupper($string,$charset);
+    }
+    // TODO: add mbstring independent code
+
+    // use vanilla string functions as last option
+    return strtoupper($string);
+}
+
+/**
+ * Counts 8bit bytes in string
+ * @param string $string tested string
+ * @return integer number of 8bit bytes
+ */
+function sq_count8bit($string) {
+    $count=0;
+    for ($i=0; $i<strlen($string); $i++) {
+        if (ord($string[$i]) > 127) $count++;
+    }
+    return $count;
+}
+
+/**
+ * Callback function to trim whitespace from a value, to be used in array_walk
+ * @param string $value value to trim
+ * @since 1.5.2 and 1.4.7
+ */
+function sq_trim_value ( &$value ) {
+    $value = trim($value);
+}
+
+/**
+  * Truncates the given string so that it has at
+  * most $max_chars characters.  NOTE that a "character"
+  * may be a multibyte character, or (optionally), an
+  * HTML entity , so this function is different than
+  * using substr() or mb_substr().
+  *
+  * NOTE that if $elipses is given and used, the returned
+  *      number of characters will be $max_chars PLUS the
+  *      length of $elipses
+  *
+  * @param string  $string    The string to truncate
+  * @param int     $max_chars The maximum allowable characters
+  * @param string  $elipses   A string that will be added to
+  *                           the end of the truncated string
+  *                           (ONLY if it is truncated) (OPTIONAL;
+  *                           default not used)
+  * @param boolean $html_entities_as_chars Whether or not to keep
+  *                                        HTML entities together
+  *                                        (OPTIONAL; default ignore
+  *                                        HTML entities)
+  *
+  * @return string The truncated string
+  *
+  * @since 1.4.20 and 1.5.2 (replaced truncateWithEntities())
+  *
+  */
+function sm_truncate_string($string, $max_chars, $elipses='',
+                            $html_entities_as_chars=FALSE)
+{
+
+   // if the length of the string is less than
+   // the allowable number of characters, just
+   // return it as is (even if it contains any
+   // HTML entities, that would just make the
+   // actual length even smaller)
+   //
+   $actual_strlen = sq_strlen($string, 'auto');
+   if ($max_chars <= 0 || $actual_strlen <= $max_chars)
+      return $string;
+
+
+   // if needed, count the number of HTML entities in
+   // the string up to the maximum character limit,
+   // pushing that limit up for each entity found
+   //
+   $adjusted_max_chars = $max_chars;
+   if ($html_entities_as_chars)
+   {
+
+      // $loop_count is needed to prevent an endless loop
+      // which is caused by buggy mbstring versions that
+      // return 0 (zero) instead of FALSE in some rare
+      // cases.  Thanks, PHP.
+      // see: http://bugs.php.net/bug.php?id=52731
+      // also: tracker $3053349
+      //
+      $loop_count = 0;
+      $entity_pos = $entity_end_pos = -1;
+      while ($entity_end_pos + 1 < $actual_strlen
+          && ($entity_pos = sq_strpos($string, '&', $entity_end_pos + 1)) !== FALSE
+          && ($entity_end_pos = sq_strpos($string, ';', $entity_pos)) !== FALSE
+          && $entity_pos <= $adjusted_max_chars
+          && $loop_count++ < $max_chars)
+      {
+         $adjusted_max_chars += $entity_end_pos - $entity_pos;
+      }
+
+
+      // this isn't necessary because sq_substr() would figure this
+      // out anyway, but we can avoid a sq_substr() call and we
+      // know that we don't have to add an elipses (this is now
+      // an accurate comparison, since $adjusted_max_chars, like
+      // $actual_strlen, does not take into account HTML entities)
+      //
+      if ($actual_strlen <= $adjusted_max_chars)
+         return $string;
+
+   }
+
+
+   // get the truncated string
+   //
+   $truncated_string = sq_substr($string, 0, $adjusted_max_chars);
+
+
+   // return with added elipses
+   //
+   return $truncated_string . $elipses;
+
+}
+
+/**
+  * Gathers the list of secuirty tokens currently
+  * stored in the user's preferences and optionally
+  * purges old ones from the list.
+  *
+  * @param boolean $purge_old Indicates if old tokens
+  *                           should be purged from the
+  *                           list ("old" is 2 days or
+  *                           older unless the administrator
+  *                           overrides that value using
+  *                           $max_security_token_age in
+  *                           config/config_local.php)
+  *                           (OPTIONAL; default is to always
+  *                           purge old tokens)
+  *
+  * @return array The list of tokens
+  *
+  * @since 1.4.19 and 1.5.2
+  *
+  */
+function sm_get_user_security_tokens($purge_old=TRUE)
+{
+
+   global $data_dir, $username, $max_token_age_days;
+
+   $tokens = getPref($data_dir, $username, 'security_tokens', '');
+   if (($tokens = unserialize($tokens)) === FALSE || !is_array($tokens))
+      $tokens = array();
+
+   // purge old tokens if necessary
+   //
+   if ($purge_old)
+   {
+      if (empty($max_token_age_days)) $max_token_age_days = 2;
+      $now = time();
+      $discard_token_date = $now - ($max_token_age_days * 86400);
+      $cleaned_tokens = array();
+      foreach ($tokens as $token => $timestamp)
+         if ($timestamp >= $discard_token_date)
+            $cleaned_tokens[$token] = $timestamp;
+      $tokens = $cleaned_tokens;
+   }
+
+   return $tokens;
+
+}
+
+/**
+  * Generates a security token that is then stored in
+  * the user's preferences with a timestamp for later
+  * verification/use.
+  *
+  * WARNING: If the administrator has turned the token system
+  *          off by setting $disable_security_tokens to TRUE in
+  *          config/config.php or the configuration tool, this
+  *          function will not store tokens in the user
+  *          preferences (but it will still generate and return
+  *          a random string).
+  *
+  * @return string A security token
+  *
+  * @since 1.4.19 and 1.5.2
+  *
+  */
+function sm_generate_security_token()
+{
+
+   global $data_dir, $username, $disable_security_tokens;
+   $max_generation_tries = 1000;
+
+   $tokens = sm_get_user_security_tokens();
+
+   $new_token = GenerateRandomString(12, '', 7);
+   $count = 0;
+   while (isset($tokens[$new_token]))
+   {
+      $new_token = GenerateRandomString(12, '', 7);
+      if (++$count > $max_generation_tries)
+      {
+         logout_error(_("Fatal token generation error; please contact your system administrator or the SquirrelMail Team"));
+         exit;
+      }
+   }
+
+   // is the token system enabled?  CAREFUL!
+   //
+   if (!$disable_security_tokens)
+   {
+      $tokens[$new_token] = time();
+      setPref($data_dir, $username, 'security_tokens', serialize($tokens));
+   }
+
+   return $new_token;
+
+}
+
+/**
+  * Validates a given security token and optionally remove it
+  * from the user's preferences if it was valid.  If the token
+  * is too old but otherwise valid, it will still be rejected.
+  *
+  * "Too old" is 2 days or older unless the administrator
+  * overrides that value using $max_security_token_age in
+  * config/config_local.php
+  *
+  * WARNING: If the administrator has turned the token system
+  *          off by setting $disable_security_tokens to TRUE in
+  *          config/config.php or the configuration tool, this
+  *          function will always return TRUE.
+  *
+  * @param string  $token           The token to validate
+  * @param int     $validity_period The number of seconds tokens are valid
+  *                                 for (set to zero to remove valid tokens
+  *                                 after only one use; use 3600 to allow
+  *                                 tokens to be reused for an hour)
+  *                                 (OPTIONAL; default is to only allow tokens
+  *                                 to be used once)
+  * @param boolean $show_error      Indicates that if the token is not
+  *                                 valid, this function should display
+  *                                 a generic error, log the user out
+  *                                 and exit - this function will never
+  *                                 return in that case.
+  *                                 (OPTIONAL; default FALSE)
+  *
+  * @return boolean TRUE if the token validated; FALSE otherwise
+  *
+  * @since 1.4.19 and 1.5.2
+  *
+  */
+function sm_validate_security_token($token, $validity_period=0, $show_error=FALSE)
+{
+
+   global $data_dir, $username, $max_token_age_days,
+          $disable_security_tokens;
+
+   // bypass token validation?  CAREFUL!
+   //
+   if ($disable_security_tokens) return TRUE;
+
+   // don't purge old tokens here because we already
+   // do it when generating tokens
+   //
+   $tokens = sm_get_user_security_tokens(FALSE);
+
+   // token not found?
+   //
+   if (empty($tokens[$token]))
+   {
+      if (!$show_error) return FALSE;
+      logout_error(_("This page request could not be verified and appears to have expired."));
+      exit;
+   }
+
+   $now = time();
+   $timestamp = $tokens[$token];
+
+   // whether valid or not, we want to remove it from
+   // user prefs if it's old enough
+   //
+   if ($timestamp < $now - $validity_period)
+   {
+      unset($tokens[$token]);
+      setPref($data_dir, $username, 'security_tokens', serialize($tokens));
+   }
+
+   // reject tokens that are too old
+   //
+   if (empty($max_token_age_days)) $max_token_age_days = 2;
+   $old_token_date = $now - ($max_token_age_days * 86400);
+   if ($timestamp < $old_token_date)
+   {
+      if (!$show_error) return FALSE;
+      logout_error(_("The current page request appears to have originated from an untrusted source."));
+      exit;
+   }
+
+   // token OK!
+   //
+   return TRUE;
+
+}
+