Partial support for IMAP LOgin Referrals: tell the user what's going on
[squirrelmail.git] / functions / imap_general.php
index 0e11590c37f27238a3178778cdeca6af48d05abe..319dcac85bc29a5f089a177f5fb07a21fc263726 100755 (executable)
@@ -3,7 +3,7 @@
 /**
  * imap_general.php
  *
- * Copyright (c) 1999-2004 The SquirrelMail Project Team
+ * Copyright (c) 1999-2005 The SquirrelMail Project Team
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
  * This implements all functions that do general imap functions.
@@ -21,8 +21,11 @@ require_once(SM_PATH . 'functions/auth.php');
 /**
  * Generates a new session ID by incrementing the last one used;
  * this ensures that each command has a unique ID.
- * @param bool unique_id
+ * @param bool $unique_id (since 1.3.0) controls use of unique 
+ *  identifiers/message sequence numbers in IMAP commands. See IMAP
+ *  rfc 'UID command' chapter.
  * @return string IMAP session id of the form 'A000'.
+ * @since 1.2.0
  */
 function sqimap_session_id($unique_id = FALSE) {
     static $sqimap_session_id = 1;
@@ -37,6 +40,17 @@ function sqimap_session_id($unique_id = FALSE) {
 /**
  * Both send a command and accept the result from the command.
  * This is to allow proper session number handling.
+ * @param resource $imap_stream imap connection resource
+ * @param string $query imap command
+ * @param boolean $handle_errors see sqimap_retrieve_imap_response()
+ * @param mixed $response
+ * @param mixed $message
+ * @param boolean $unique_id (since 1.3.0) controls use of unique 
+ *  identifiers/message sequence numbers in IMAP commands. See IMAP
+ *  rfc 'UID command' chapter.
+ * @return mixed returns false on imap error. displays error message 
+ *  if imap stream is not available.
+ * @since 1.2.3
  */
 function sqimap_run_command_list ($imap_stream, $query, $handle_errors, &$response, &$message, $unique_id = false) {
     if ($imap_stream) {
@@ -47,13 +61,13 @@ function sqimap_run_command_list ($imap_stream, $query, $handle_errors, &$respon
         $read = sqimap_retrieve_imap_response ($imap_stream, $tag, $handle_errors, $response, $message, $query );
         /* get the response and the message */
         $message = $message[$tag];
-        $response = $response[$tag]; 
+        $response = $response[$tag];
         return $read[$tag];
     } else {
         global $squirrelmail_language, $color;
         set_up_language($squirrelmail_language);
         require_once(SM_PATH . 'functions/display_messages.php');
-        $string = "<b><font color=$color[2]>\n" .
+        $string = "<b><font color=\"$color[2]\">\n" .
                 _("ERROR : No available imapstream.") .
                 "</b></font>\n";
         error_box($string,$color);
@@ -61,18 +75,34 @@ function sqimap_run_command_list ($imap_stream, $query, $handle_errors, &$respon
     }
 }
 
-function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response, 
+/**
+ * @param resource $imap_stream imap connection resource
+ * @param string $query imap command
+ * @param boolean $handle_errors see sqimap_retrieve_imap_response()
+ * @param mixed $response
+ * @param mixed $message
+ * @param boolean $unique_id (since 1.3.0) controls use of unique 
+ *  identifiers/message sequence numbers in IMAP commands. See IMAP
+ *  rfc 'UID command' chapter.
+ * @param mixed $filter (since 1.4.1 and 1.5.0)
+ * @param mixed $outputstream (since 1.4.1 and 1.5.0)
+ * @param mixed $no_return (since 1.4.1 and 1.5.0)
+ * @return mixed returns false on imap error. displays error message 
+ *  if imap stream is not available.
+ * @since 1.2.3
+ */
+function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response,
                             &$message, $unique_id = false,$filter=false,
                              $outputstream=false,$no_return=false) {
     if ($imap_stream) {
         $sid = sqimap_session_id($unique_id);
-        fputs ($imap_stream, $sid . ' ' . $query . "\r\n"); 
+        fputs ($imap_stream, $sid . ' ' . $query . "\r\n");
         $tag_uid_a = explode(' ',trim($sid));
         $tag = $tag_uid_a[0];
-   
+
         $read = sqimap_read_data ($imap_stream, $tag, $handle_errors, $response,
                                   $message, $query,$filter,$outputstream,$no_return);
-        if (empty($read)) {    //Imap server dropped its connection
+        if (empty($read)) {    //Imap server dropped its connection
             $response = '';
             $message = '';
             return false;
@@ -80,7 +110,7 @@ function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response,
         /* retrieve the response and the message */
         $response = $response[$tag];
         $message  = $message[$tag];
-    
+
         if (!empty($read[$tag])) {
             return $read[$tag][0];
         } else {
@@ -90,14 +120,21 @@ function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response,
         global $squirrelmail_language, $color;
         set_up_language($squirrelmail_language);
         require_once(SM_PATH . 'functions/display_messages.php');
-        $string = "<b><font color=$color[2]>\n" .
+        $string = "<b><font color=\"$color[2]\">\n" .
                 _("ERROR : No available imapstream.") .
                 "</b></font>\n";
         error_box($string,$color);
         return false;
-    }    
+    }
 }
 
+/**
+ * @param mixed $new_query
+ * @param string $tag
+ * @param array $aQuery
+ * @param boolean $unique_id
+ * @since 1.5.0
+ */
 function sqimap_prepare_pipelined_query($new_query,&$tag,&$aQuery,$unique_id) {
     $sid = sqimap_session_id($unique_id);
     $tag_uid_a = explode(' ',trim($sid));
@@ -106,19 +143,31 @@ function sqimap_prepare_pipelined_query($new_query,&$tag,&$aQuery,$unique_id) {
     $aQuery[$tag] = $query;
 }
 
-function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors, 
+/**
+ * @param stream $imap_stream
+ * @param array $aQueryList
+ * @param boolean $handle_errors
+ * @param array $aServerResponse
+ * @param array $aServerMessage
+ * @param boolean $unique_id
+ * @param mixed $filter see sqimap_retrieve_imap_response()
+ * @param mixed $outputstream see sqimap_retrieve_imap_response()
+ * @param mixed $no_return see sqimap_retrieve_imap_response()
+ * @since 1.5.0
+ */
+function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors,
                        &$aServerResponse, &$aServerMessage, $unique_id = false,
-                       $filter=false,$outputstream=false,$no_return=false) {    
+                       $filter=false,$outputstream=false,$no_return=false) {
     $aResponse = false;
 
-    /* 
+    /*
        Do not fire all calls at once to the imap-server but split the calls up
-       in portions of $iChunkSize. If we do not do that I think we misbehave as 
+       in portions of $iChunkSize. If we do not do that I think we misbehave as
        IMAP client or should handle BYE calls if the IMAP-server drops the
        connection because the number of queries is to large. This isn't tested
        but a wild guess how it could work in the field.
-       
-       After testing it on Exchange 2000 we discovered that a chunksize of 32 
+
+       After testing it on Exchange 2000 we discovered that a chunksize of 32
        was quicker then when we raised it to 128.
     */
     $iQueryCount = count($aQueryList);
@@ -138,11 +187,11 @@ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors
                 if (next($aQueryList) === false) break;
             }
             $aQueryChunks[] = $aTmp;
-        } 
+        }
     } else {
         $aQueryChunks = array_chunk($aQueryList,$iChunkSize,true);
     }
-    
+
     for ($i=0;$i<$iLoops;++$i) {
         $aQuery = $aQueryChunks[$i];
         foreach($aQuery as $tag => $query) {
@@ -151,7 +200,7 @@ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors
         }
         foreach($aQuery as $tag => $query) {
             if ($aResults[$tag] == false) {
-                $aReturnedResponse = sqimap_retrieve_imap_response ($imap_stream, $tag, 
+                $aReturnedResponse = sqimap_retrieve_imap_response ($imap_stream, $tag,
                                     $handle_errors, $response, $message, $query,
                                     $filter,$outputstream,$no_return);
                 foreach ($aReturnedResponse as $returned_tag => $aResponse) {
@@ -169,11 +218,12 @@ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors
     return $aResults;
 }
 
-/** 
+/**
  * Custom fgets function: gets a line from the IMAP-server,
  * no matter how big it may be.
  * @param stream imap_stream the stream to read from
  * @return string a line
+ * @since 1.2.8
  */
 function sqimap_fgets($imap_stream) {
     $read = '';
@@ -195,6 +245,15 @@ function sqimap_fgets($imap_stream) {
     return $results;
 }
 
+/**
+ * @param stream $imap_stream
+ * @param integer $iSize
+ * @param mixed $filter see sqimap_retrieve_imap_response()
+ * @param mixed $outputstream see sqimap_retrieve_imap_response()
+ * @param mixed $no_return see sqimap_retrieve_imap_response()
+ * @return string
+ * @since 1.4.1
+ */
 function sqimap_fread($imap_stream,$iSize,$filter=false,
                       $outputstream=false, $no_return=false) {
     if (!$filter || !$outputstream) {
@@ -210,7 +269,7 @@ function sqimap_fread($imap_stream,$iSize,$filter=false,
     $iRetrieved = 0;
     $results = '';
     $sRead = $sReadRem = '';
-    // NB: fread can also stop at end of a packet on sockets. 
+    // NB: fread can also stop at end of a packet on sockets.
     while ($iRetrieved < $iSize) {
         $sRead = fread($imap_stream,$iBufferSize);
         $iLength = strlen($sRead);
@@ -219,20 +278,20 @@ function sqimap_fread($imap_stream,$iSize,$filter=false,
         if ($iRemaining < $iBufferSize) {
             $iBufferSize = $iRemaining;
         }
-        if (!$sRead) {
+        if ($sRead == '') {
             $results = false;
             break;
         }
-        if ($sReadRem) {
+        if ($sReadRem != '') {
             $sRead = $sReadRem . $sRead;
             $sReadRem = '';
         }
 
-        if ($filter && $sRead) {
-           // in case the filter is base64 decoding we return a remainder 
+        if ($filter && $sRead != '') {
+           // in case the filter is base64 decoding we return a remainder
            $sReadRem = $filter($sRead);
         }
-        if ($outputstream && $sRead) {
+        if ($outputstream && $sRead != '') {
            if (is_resource($outputstream)) {
                fwrite($outputstream,$sRead);
            } else if ($outputstream == 'php://stdout') {
@@ -241,36 +300,37 @@ function sqimap_fread($imap_stream,$iSize,$filter=false,
         }
         if ($no_return) {
             $sRead = '';
-        } else {    
+        } else {
             $results .= $sRead;
         }
     }
-    return $results;       
-}        
+    return $results;
+}
 
 
 /**
  * Obsolete function, inform plugins that use it
- * @deprecated use sqimap_run_command or sqimap_run_command_list instead
+ * @since 1.1.3
+ * @deprecated (since 1.5.0) use sqimap_run_command or sqimap_run_command_list instead
  */
-function sqimap_read_data_list($imap_stream, $tag, $handle_errors, 
+function sqimap_read_data_list($imap_stream, $tag, $handle_errors,
           &$response, &$message, $query = '') {
     global $color, $squirrelmail_language;
     set_up_language($squirrelmail_language);
     require_once(SM_PATH . 'functions/display_messages.php');
-    $string = "<b><font color=$color[2]>\n" .
+    $string = "<b><font color=\"$color[2]\">\n" .
         _("ERROR : Bad function call.") .
-        "</b><br>\n" .
+        "</b><br />\n" .
         _("Reason:") . ' '.
-          'There is a plugin installed which make use of the  <br>' .
-          'SquirrelMail internal function sqimap_read_data_list.<br>'.
-          'Please adapt the installed plugin and let it use<br>'.
-          'sqimap_run_command or sqimap_run_command_list instead<br><br>'.
-          'The following query was issued:<br>'.
-           htmlspecialchars($query) . '<br>' . "</font><br>\n";
+          'There is a plugin installed which make use of the  <br />' .
+          'SquirrelMail internal function sqimap_read_data_list.<br />'.
+          'Please adapt the installed plugin and let it use<br />'.
+          'sqimap_run_command or sqimap_run_command_list instead<br /><br />'.
+          'The following query was issued:<br />'.
+           htmlspecialchars($query) . '<br />' . "</font><br />\n";
     error_box($string,$color);
-    echo '</body></html>';        
-    exit; 
+    echo '</body></html>';
+    exit;
 }
 
 /**
@@ -281,6 +341,7 @@ function sqimap_read_data_list($imap_stream, $tag, $handle_errors,
  * @param string message optional error message
  * @param string $link an optional link to try again
  * @return void
+ * @since 1.5.0
  */
 function sqimap_error_box($title, $query = '', $message_title = '', $message = '', $link = '')
 {
@@ -288,17 +349,17 @@ function sqimap_error_box($title, $query = '', $message_title = '', $message = '
 
     set_up_language($squirrelmail_language);
     require_once(SM_PATH . 'functions/display_messages.php');
-    $string = "<font color=$color[2]><b>\n" . $title . "</b><br>\n";
+    $string = "<font color=\"$color[2]\"><b>\n" . $title . "</b><br />\n";
     $cmd = explode(' ',$query);
     $cmd= strtolower($cmd[0]);
 
     if ($query != '' &&  $cmd != 'login')
-        $string .= _("Query:") . ' ' . htmlspecialchars($query) . '<br>';
+        $string .= _("Query:") . ' ' . htmlspecialchars($query) . '<br />';
     if ($message_title != '')
         $string .= $message_title;
     if ($message != '')
         $string .= htmlspecialchars($message);
-    $string .= "</font><br>\n";
+    $string .= "</font><br />\n";
     if ($link != '')
         $string .= $link;
     error_box($string,$color);
@@ -308,8 +369,18 @@ function sqimap_error_box($title, $query = '', $message_title = '', $message = '
  * Reads the output from the IMAP stream.  If handle_errors is set to true,
  * this will also handle all errors that are received.  If it is not set,
  * the errors will be sent back through $response and $message.
+ * @param stream $imap_stream
+ * @param mixed $tag
+ * @param boolean $handle_errors
+ * @param array $response
+ * @param array $message
+ * @param mixed $query
+ * @param mixed $filter
+ * @param mixed $outputstream
+ * @param mixed $no_return
+ * @since 1.5.0
  */
-function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, 
+function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
           &$response, &$message, $query = '',
            $filter = false, $outputstream = false, $no_return = false) {
     global $color, $squirrelmail_language;
@@ -320,7 +391,7 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
     $resultlist = array();
     $data = array();
     $read = sqimap_fgets($imap_stream);
-    $i = $k = 0;
+    $i = 0;
     while ($read) {
         $char = $read{0};
         switch ($char)
@@ -359,7 +430,7 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
                         break 3; /* switch switch while */
                     }
                   break;
-                  default: 
+                  default:
                     /* this shouldn't happen */
                     $response[$found_tag] = $arg;
                     $message[$found_tag] = trim(substr($read,$i+strlen($arg)));
@@ -375,7 +446,7 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
             }
             $read = sqimap_fgets($imap_stream);
             if ($read === false) { /* error */
-                 break 3; /* switch switch while */
+                 break 2; /* switch while */
             }
             break;
           } // end case $tag{0}
@@ -408,7 +479,7 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
                                 $fetch_data[] = $line ."\n";
                             }
                             /* release not neaded data */
-                            unset($aLiteral); 
+                            unset($aLiteral);
                             /* next fgets belongs to this fetch because
                                we just got the exact literalsize and there
                                must follow data to complete the response */
@@ -462,12 +533,12 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
                     $s = substr($read,-3);
                 } while ($s === "}\r\n");
                 break 1;
-            }    
+            }
             break;
           } // end case '*'
         }   // end switch
     } // end while
-    
+
     /* error processing in case $read is false */
     if ($read === false) {
         // try to retrieve an untagged bye respons from the results
@@ -480,18 +551,18 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
             echo '</body></html>';
             exit;
         } else if ($handle_errors) {
-            unset($data); 
+            unset($data);
             sqimap_error_box(_("ERROR : Connection dropped by imap-server."), $query);
             exit;
         }
     }
-    
+
     /* Set $resultlist array */
     if (!empty($data)) {
         //$resultlist[] = $data;
     }
     elseif (empty($resultlist)) {
-        $resultlist[] = array(); 
+        $resultlist[] = array();
     }
 
     /* Return result or handle errors */
@@ -502,7 +573,7 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
     case 'OK':
         return $aResponse;
         break;
-    case 'NO': 
+    case 'NO':
         /* ignore this error from M$ exchange, it is not fatal (aka bug) */
         if (strstr($message[$tag], 'command resulted in') === false) {
             sqimap_error_box(_("ERROR : Could not complete request."), $query, _("Reason Given: "), $message[$tag]);
@@ -510,51 +581,44 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
             exit;
         }
         break;
-    case 'BAD': 
+    case 'BAD':
         sqimap_error_box(_("ERROR : Bad or malformed request."), $query, _("Server responded: "), $message[$tag]);
-        echo '</body></html>';        
-        exit; 
-    case 'BYE': 
+        echo '</body></html>';
+        exit;
+    case 'BYE':
         sqimap_error_box(_("ERROR : Imap server closed the connection."), $query, _("Server responded: "), $message[$tag]);
-        echo '</body></html>';        
+        echo '</body></html>';
         exit;
-    default: 
+    default:
         sqimap_error_box(_("ERROR : Unknown imap response."), $query, _("Server responded: "), $message[$tag]);
        /* the error is displayed but because we don't know the reponse we
           return the result anyway */
-       return $aResponse;    
+       return $aResponse;
        break;
     }
 }
 
-function sqimap_read_data ($imap_stream, $tag_uid, $handle_errors, 
+/**
+ * @param stream $imap_stream
+ * @param string $tag_uid
+ * @param boolean $handle_errors
+ * @param array $response
+ * @param array $message
+ * @param mixed $query (since 1.2.5)
+ * @param mixed $filter (since 1.4.1) see sqimap_retrieve_imap_response()
+ * @param mixed $outputstream (since 1.4.1) see sqimap_retrieve_imap_response()
+ * @param mixed $no_return (since 1.4.1) see sqimap_retrieve_imap_response()
+ */
+function sqimap_read_data ($imap_stream, $tag_uid, $handle_errors,
                            &$response, &$message, $query = '',
                            $filter=false,$outputstream=false,$no_return=false) {
 
     $tag_uid_a = explode(' ',trim($tag_uid));
     $tag = $tag_uid_a[0];
 
-    $res = sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, 
-              $response, $message, $query,$filter,$outputstream,$no_return); 
-    /* sqimap_read_data should be called for one response
-       but since it just calls sqimap_retrieve_imap_response which 
-       handles multiple responses we need to check for that
-       and merge the $res array IF they are seperated and 
-       IF it was a FETCH response. */
-  
-//    if (isset($res[1]) && is_array($res[1]) && isset($res[1][0]) 
-//        && preg_match('/^\* \d+ FETCH/', $res[1][0])) {
-//        $result = array();
-//        foreach($res as $index=>$value) {
-//            $result = array_merge($result, $res["$index"]);
-//        }
-//    }
-    if (isset($result)) {
-        return $result[$tag];
-    }
-    else {
-        return $res;
-    }
+    $res = sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
+              $response, $message, $query,$filter,$outputstream,$no_return);
+    return $res;
 }
 
 /**
@@ -564,9 +628,10 @@ function sqimap_read_data ($imap_stream, $tag_uid, $handle_errors,
  * @param int port port number to connect to
  * @param bool tls whether to use TLS when connecting.
  * @return imap-stream resource identifier
+ * @since 1.5.0 (usable only in 1.5.1 or later)
  */
 function sqimap_create_stream($server,$port,$tls=false) {
-    global $username, $use_imap_tls;
+    global $squirrelmail_language;
 
     if ($tls == true) {
         if ((check_php_version(4,3)) and (extension_loaded('openssl'))) {
@@ -574,23 +639,22 @@ function sqimap_create_stream($server,$port,$tls=false) {
             $server = 'tls://' . $server;
         } else {
             require_once(SM_PATH . 'functions/display_messages.php');
-            $string = "Unable to connect to IMAP server!<br>TLS is enabled, but this " .
-              "version of PHP does not support TLS sockets, or is missing the openssl " .
-              "extension.<br><br>Please contact your system administrator.";
-            logout_error($string,$color);
+            logout_error( sprintf(_("Error connecting to IMAP server: %s."), $server).
+                '<br />'.
+                _("TLS is enabled, but this version of PHP does not support TLS sockets, or is missing the openssl extension.").
+                '<br /><br />'.
+                _("Please contact your system administrator and report this error.") );
         }
     }
 
-    $imap_stream = fsockopen($server, $port, $error_number, $error_string, 15);
+    $imap_stream = @fsockopen($server, $port, $error_number, $error_string, 15);
 
     /* Do some error correction */
     if (!$imap_stream) {
         set_up_language($squirrelmail_language, true);
         require_once(SM_PATH . 'functions/display_messages.php');
-        $string = sprintf (_("Error connecting to IMAP server: %s.") .
-           "<br>\r\n", $server) .
-           "$error_number : $error_string<br>\r\n";
-        logout_error($string,$color);
+        logout_error( sprintf(_("Error connecting to IMAP server: %s."), $server).
+            "<br />\r\n$error_number : $error_string<br />\r\n" );
         exit;
     }
     $server_info = fgets ($imap_stream, 1024);
@@ -600,6 +664,12 @@ function sqimap_create_stream($server,$port,$tls=false) {
 /**
  * Logs the user into the imap server.  If $hide is set, no error messages
  * will be displayed.  This function returns the imap connection handle.
+ * @param string $username user name
+ * @param string $password encrypted password
+ * @param string $imap_server_address address of imap server
+ * @param integer $imap_port port of imap server
+ * @param boolean $hide controls display connection errors
+ * @return stream
  */
 function sqimap_login ($username, $password, $imap_server_address, $imap_port, $hide) {
     global $color, $squirrelmail_language, $onetimepad, $use_imap_tls,
@@ -621,7 +691,7 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
     $password = OneTimePadDecrypt($password, $onetimepad);
 
     if (($imap_auth_mech == 'cram-md5') OR ($imap_auth_mech == 'digest-md5')) {
-    // We're using some sort of authentication OTHER than plain or login
+        // We're using some sort of authentication OTHER than plain or login
         $tag=sqimap_session_id(false);
         if ($imap_auth_mech == 'digest-md5') {
             $query = $tag . " AUTHENTICATE DIGEST-MD5\r\n";
@@ -643,7 +713,7 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
             fputs($imap_stream,$reply);
             $read=sqimap_fgets($imap_stream);
             if ($imap_auth_mech == 'digest-md5') {
-            // DIGEST-MD5 has an extra step..
+                // DIGEST-MD5 has an extra step..
                 if (substr($read,0,1) == '+') { // OK so far..
                     fputs($imap_stream,"\r\n");
                     $read=sqimap_fgets($imap_stream);
@@ -653,7 +723,7 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
             $response=$results[1];
             $message=$results[2];
         } else {
-        // Fake the response, so the error trap at the bottom will work
+            // Fake the response, so the error trap at the bottom will work
             $response="BAD";
             $message='IMAP server does not appear to support the authentication method selected.';
             $message .= '  Please contact your system administrator.';
@@ -712,14 +782,14 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
                 set_up_language($squirrelmail_language, true);
                 require_once(SM_PATH . 'functions/display_messages.php');
                 if ($response == 'BAD') {
-                    $string = sprintf (_("Bad request: %s")."<br>\r\n", $message);
+                    $string = sprintf (_("Bad request: %s")."<br />\r\n", $message);
                 } else {
-                    $string = sprintf (_("Unknown error: %s") . "<br>\n", $message);
+                    $string = sprintf (_("Unknown error: %s") . "<br />\n", $message);
                 }
                 if (isset($read) && is_array($read)) {
-                    $string .= '<br>' . _("Read data:") . "<br>\n";
+                    $string .= '<br />' . _("Read data:") . "<br />\n";
                     foreach ($read as $line) {
-                        $string .= htmlspecialchars($line) . "<br>\n";
+                        $string .= htmlspecialchars($line) . "<br />\n";
                     }
                 }
                 error_box($string,$color);
@@ -739,6 +809,8 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
                 set_up_language($squirrelmail_language, true);
                 include_once(SM_PATH . 'functions/display_messages.php' );
                 sqsession_destroy();
+                /* terminate the session nicely */
+                sqimap_logout($imap_stream);
                 logout_error( _("Unknown user or password incorrect.") );
                 exit;
             }
@@ -746,6 +818,23 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
             exit;
         }
     }
+
+    /* Special error case:
+     * Login referrals. The server returns:
+        * ? OK [REFERRAL <imap url>]
+        * Check RFC 2221 for details. Since we do not support login referrals yet
+        * we log the user out.
+        */
+    if ( strpos($message, "REFERRAL") ) {
+        sqimap_logout($imap_stream);   
+        set_up_language($squirrelmail_language, true);
+        include_once(SM_PATH . 'functions/display_messages.php' );
+        sqsession_destroy();
+        logout_error( _("Your mailbox is not located on this server.<br>".
+                          "Try a different server or consult your Administrator") );
+        exit;
+    }
+    
     return $imap_stream;
 }
 
@@ -765,6 +854,11 @@ function sqimap_logout ($imap_stream) {
  * Retreive the CAPABILITY string from the IMAP server.
  * If capability is set, returns only that specific capability,
  * else returns array of all capabilities.
+ * @param $imap_stream
+ * @param string $capability (optional since 1.3.0)
+ * @return mixed (string if $capability is set and found, 
+ *  false, if $capability is set and not found,
+ *  array if $capability not set)
  */
 function sqimap_capability($imap_stream, $capability='') {
     global $sqimap_capabilities;
@@ -795,6 +889,8 @@ function sqimap_capability($imap_stream, $capability='') {
 
 /**
  * Returns the delimeter between mailboxes: INBOX/Test, or INBOX.Test
+ * @param stream $imap_stream
+ * @return string
  */
 function sqimap_get_delimiter ($imap_stream = false) {
     global $sqimap_delimiter, $optional_delimiter;
@@ -833,7 +929,7 @@ function sqimap_get_delimiter ($imap_stream = false) {
         } else {
             fputs ($imap_stream, ". LIST \"INBOX\" \"\"\r\n");
             $read = sqimap_read_data($imap_stream, '.', true, $a, $b);
-            $read = $read['.'][0];     //sqimap_read_data() now returns a tag array of response array
+            $read = $read['.'][0];    //sqimap_read_data() now returns a tag array of response array
             $quote_position = strpos ($read[0], '"');
             $sqimap_delimiter = substr ($read[0], $quote_position+1, 1);
         }
@@ -845,17 +941,19 @@ function sqimap_get_delimiter ($imap_stream = false) {
  * This encodes a mailbox name for use in IMAP commands.
  * @param string what the mailbox to encode
  * @return string the encoded mailbox string
+ * @since 1.5.0
  */
 function sqimap_encode_mailbox_name($what)
 {
-       if (ereg("[\"\\\r\n]", $what))
-               return '{' . strlen($what) . "}\r\n" . $what;   /* 4.3 literal form */
-       return '"' . $what . '"';       /* 4.3 quoted string form */
+    if (ereg("[\"\\\r\n]", $what))
+        return '{' . strlen($what) . "}\r\n" . $what;        /* 4.3 literal form */
+    return '"' . $what . '"';        /* 4.3 quoted string form */
 }
 
-
 /**
  * Gets the number of messages in the current mailbox.
+ *
+ * OBSOLETE use sqimap_status_messages instead.
  */
 function sqimap_get_num_messages ($imap_stream, $mailbox) {
     $read_ary = sqimap_run_command ($imap_stream, 'EXAMINE ' . sqimap_encode_mailbox_name($mailbox), false, $result, $message);
@@ -866,176 +964,35 @@ function sqimap_get_num_messages ($imap_stream, $mailbox) {
     }
     return false; //"BUG! Couldn't get number of messages in $mailbox!";
 }
+include_once(SM_PATH . 'functions/rfc822address.php');
 
+/**
+ * OBSOLETE FUNCTION should be removed after mailbox_display,
+ * printMessage function is adapted
+ */
 function parseAddress($address, $max=0) {
-    $aTokens = array();
-    $aAddress = array();
-    $iCnt = strlen($address);
-    $aSpecials = array('(' ,'<' ,',' ,';' ,':');
-    $aReplace =  array(' (',' <',' ,',' ;',' :');
-    $address = str_replace($aSpecials,$aReplace,$address);
-    $i = $iAddrFound = $bGroup = 0;
-    while ($i < $iCnt) {
-        $cChar = $address{$i};
-        switch($cChar)
-        {
-        case '<':
-            $iEnd = strpos($address,'>',$i+1);
-            if (!$iEnd) {
-               $sToken = substr($address,$i);
-               $i = $iCnt;
-            } else {
-               $sToken = substr($address,$i,$iEnd - $i +1);
-               $i = $iEnd;
-            }
-            $sToken = str_replace($aReplace, $aSpecials,$sToken);
-            $aTokens[] = $sToken;
-            break;
-        case '"':
-            $iEnd = strpos($address,$cChar,$i+1);
-            if ($iEnd) {
-               // skip escaped quotes
-               $prev_char = $address{$iEnd-1};
-               while ($prev_char === '\\' && substr($address,$iEnd-2,2) !== '\\\\') {
-                   $iEnd = strpos($address,$cChar,$iEnd+1);
-                   if ($iEnd) {
-                      $prev_char = $address{$iEnd-1};
-                   } else {
-                      $prev_char = false;
-                   }
-               }
-            }
-            if (!$iEnd) {
-                $sToken = substr($address,$i);
-                $i = $iCnt;
-            } else {
-                // also remove the surrounding quotes
-                $sToken = substr($address,$i+1,$iEnd - $i -1);
-                $i = $iEnd;
-            }
-            $sToken = str_replace($aReplace, $aSpecials,$sToken);
-            if ($sToken) $aTokens[] = $sToken;
-            break;
-        case '(':
-            $iEnd = strpos($address,')',$i);
-            if (!$iEnd) {
-                $sToken = substr($address,$i);
-                $i = $iCnt;
-            } else {
-                $sToken = substr($address,$i,$iEnd - $i + 1);
-                $i = $iEnd;
-            }
-            $sToken = str_replace($aReplace, $aSpecials,$sToken);
-            $aTokens[] = $sToken;
-            break;
-        case ',':
-            ++$iAddrFound;
-        case ';':
-            if (!$bGroup) {
-               ++$iAddrFound;
-            } else {
-               $bGroup = false;
-            }
-            if ($max && $max == $iAddrFound) {
-               break 2;
-            } else {
-               $aTokens[] = $cChar;
-               break;
-            }
-        case ':':
-           $bGroup = true;
-        case ' ':
-            $aTokens[] = $cChar;
-            break;
-        default:
-            $iEnd = strpos($address,' ',$i+1);
-            if ($iEnd) {
-                $sToken = trim(substr($address,$i,$iEnd - $i));
-                $i = $iEnd-1;
-            } else {
-                $sToken = trim(substr($address,$i));
-                $i = $iCnt;
-            }
-            if ($sToken) $aTokens[] = $sToken;
-        }
-        ++$i;
-    }
-    $sPersonal = $sEmail = $sComment = $sGroup = '';
-    $aStack = $aComment = array();
-    foreach ($aTokens as $sToken) {
-        if ($max && $max == count($aAddress)) {
-            return $aAddress;
-        }
-        $cChar = $sToken{0};
-        switch ($cChar)
-        {
-          case '=':
-          case '"':
-          case ' ':
-            $aStack[] = $sToken; 
-            break;
-          case '(':
-            $aComment[] = substr($sToken,1,-1);
-            break;
-          case ';':
-            if ($sGroup) {
-                $sEmail = trim(implode(' ',$aStack));
-                $aAddress[] = array($sGroup,$sEmail);
-                $aStack = $aComment = array();
-                $sGroup = '';
-                break;
-            }
-          case ',':
-            if (!$sEmail) {
-                while (count($aStack) && !$sEmail) {
-                    $sEmail = trim(array_pop($aStack));
-                }
-            }
-            if (count($aStack)) {
-                $sPersonal = trim(implode('',$aStack));
-            } else { 
-                $sPersonal = '';
-            }
-            if (!$sPersonal && count($aComment)) {
-                $sComment = implode(' ',$aComment);
-                $sPersonal .= $sComment;
-            }
-            $aAddress[] = array($sEmail,$sPersonal);
-            $sPersonal = $sComment = $sEmail = '';
-            $aStack = $aComment = array();
-            break;
-          case ':': 
-            $sGroup = implode(' ',$aStack); break;
-            $aStack = array();
-            break;
-          case '<':
-            $sEmail = trim(substr($sToken,1,-1));
-            break;
-          case '>':
-            /* skip */
-            break; 
-          default: $aStack[] = $sToken; break;
-        }
-    }
-    /* now do the action again for the last address */
-    if (!$sEmail) {
-        while (count($aStack) && !$sEmail) {
-            $sEmail = trim(array_pop($aStack));
-        }
-    }
-    if (count($aStack)) {
-        $sPersonal = trim(implode('',$aStack));
-    } else {
-        $sPersonal = '';
-    }
-    if (!$sPersonal && count($aComment)) {
-        $sComment = implode(' ',$aComment);
-        $sPersonal .= $sComment;
-    }
-    $aAddress[] = array($sEmail,$sPersonal);
-    return $aAddress;
-} 
+    $aAddress = parseRFC822Address($address,array('limit'=> $max));
+    /*
+     * Because the expected format of the array element is changed we adapt it now.
+     * This also implies that this function is obsolete and should be removed after the
+     * rest of the source is adapted. See Rfc822Address.php for the new function.
+     */
+     array_walk($aAddress, '_adaptAddress');
+     return $aAddress;
+}
 
+/**
+ * OBSOLETE FUNCTION should be removed after mailbox_display,
+ * printMessage function is adapted
+ */
+function _adaptAddress(&$aAddr,$k) {
+   $sPersonal = (isset($aAddr[SQM_ADDR_PERSONAL]) && $aAddr[SQM_ADDR_PERSONAL]) ?
+       $aAddr[SQM_ADDR_PERSONAL] : '';
+   $sEmail = ($aAddr[SQM_ADDR_HOST]) ?
+       $aAddr[SQM_ADDR_MAILBOX] . '@'.$aAddr[SQM_ADDR_HOST] :
+       $aAddr[SQM_ADDR_MAILBOX];
+   $aAddr = array($sEmail,$sPersonal);
+}
 
 /**
  * Returns the number of unseen messages in this folder.
@@ -1051,7 +1008,7 @@ function sqimap_unseen_messages ($imap_stream, $mailbox) {
  * Default it returns MESSAGES,UNSEEN and RECENT
  * Supported status items are MESSAGES, UNSEEN, RECENT, UIDNEXT and UIDVALIDITY
  */
-function sqimap_status_messages ($imap_stream, $mailbox, 
+function sqimap_status_messages ($imap_stream, $mailbox,
                        $aStatusItems = array('MESSAGES','UNSEEN','RECENT')) {
 
     $aStatusItems = implode(' ',$aStatusItems);
@@ -1069,17 +1026,17 @@ function sqimap_status_messages ($imap_stream, $mailbox,
         }
         if (preg_match('/RECENT\s+([0-9]+)/i', $read_ary[$i], $regs)) {
             $recent = $regs[1];
-        }        
+        }
         if (preg_match('/UIDNEXT\s+([0-9]+)/i', $read_ary[$i], $regs)) {
             $uidnext = $regs[1];
-        }        
+        }
         if (preg_match('/UIDVALIDITY\s+([0-9]+)/i', $read_ary[$i], $regs)) {
             $uidvalidity = $regs[1];
-        }        
+        }
         $i++;
     }
-    return array('MESSAGES' => $messages, 
-                 'UNSEEN'=>$unseen, 
+    return array('MESSAGES' => $messages,
+                 'UNSEEN'=>$unseen,
                  'RECENT' => $recent,
                  'UIDNEXT' => $uidnext,
                  'UIDVALIDITY' => $uidvalidity);
@@ -1092,35 +1049,42 @@ function sqimap_status_messages ($imap_stream, $mailbox,
 function sqimap_append ($imap_stream, $sent_folder, $length) {
     fputs ($imap_stream, sqimap_session_id() . ' APPEND ' . sqimap_encode_mailbox_name($sent_folder) . " (\\Seen) \{$length}\r\n");
     $tmp = fgets ($imap_stream, 1024);
+    sqimap_append_checkresponse($tmp, $sent_folder);
 }
 
 function sqimap_append_done ($imap_stream, $folder='') {
-    global $squirrelmail_language, $color;
     fputs ($imap_stream, "\r\n");
     $tmp = fgets ($imap_stream, 1024);
-    if (preg_match("/(.*)(BAD|NO)(.*)$/", $tmp, $regs)) {
+    sqimap_append_checkresponse($tmp, $folder);
+}
+
+function sqimap_append_checkresponse($response, $folder) {
+    
+    if (preg_match("/(.*)(BAD|NO)(.*)$/", $response, $regs)) {
+        global $squirrelmail_language, $color;
         set_up_language($squirrelmail_language);
         require_once(SM_PATH . 'functions/display_messages.php');
+
         $reason = $regs[3];
         if ($regs[2] == 'NO') {
-           $string = "<b><font color=$color[2]>\n" .
+           $string = "<b><font color=\"$color[2]\">\n" .
                   _("ERROR : Could not append message to") ." $folder." .
-                  "</b><br>\n" .
+                  "</b><br />\n" .
                   _("Server responded: ") .
-                  $reason . "<br>\n";
+                  $reason . "<br />\n";
            if (preg_match("/(.*)(quota)(.*)$/i", $reason, $regs)) {
-              $string .= _("Solution: ") . 
-            _("Remove unneccessary messages from your folder and start with your Trash folder.") 
-              ."<br>\n";
+              $string .= _("Solution: ") .
+            _("Remove unneccessary messages from your folder and start with your Trash folder.")
+              ."<br />\n";
            }
            $string .= "</font>\n";
            error_box($string,$color);
         } else {
-           $string = "<b><font color=$color[2]>\n" .
+           $string = "<b><font color=\"$color[2]\">\n" .
                   _("ERROR : Bad or malformed request.") .
-                  "</b><br>\n" .
+                  "</b><br />\n" .
                   _("Server responded: ") .
-                  $tmp . "</font><br>\n";
+                  $reason . "</font><br />\n";
            error_box($string,$color);
            exit;
         }
@@ -1137,13 +1101,13 @@ function sqimap_get_user_server ($imap_server, $username) {
 
 /**
  * This is an example that gets imapservers from yellowpages (NIS).
- * you can simple put map:map_yp_alias in your $imap_server_address 
+ * you can simple put map:map_yp_alias in your $imap_server_address
  * in config.php use your own function instead map_yp_alias to map your
  * LDAP whatever way to find the users imapserver.
  */
 function map_yp_alias($username) {
    $yp = `ypmatch $username aliases`;
    return chop(substr($yp, strlen($username)+1));
-} 
+}
 
 ?>