functions/imap_general.php

   1 <?php
   2
   3 /**
   4  * imap_general.php
   5  *
   6  * This implements all functions that do general IMAP functions.
   7  *
   8  * @copyright &copy; 1999-2007 The SquirrelMail Project Team
   9  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  10  * @version $Id$
  11  * @package squirrelmail
  12  * @subpackage imap
  13  */
  14
  15 /** Includes.. */
  16
  17 require_once(SM_PATH . 'functions/rfc822address.php');
  18
  19
  20 /**
  21  * Generates a new session ID by incrementing the last one used;
  22  * this ensures that each command has a unique ID.
  23  * @param bool $unique_id (since 1.3.0) controls use of unique
  24  *  identifiers/message sequence numbers in IMAP commands. See IMAP
  25  *  rfc 'UID command' chapter.
  26  * @return string IMAP session id of the form 'A000'.
  27  * @since 1.2.0
  28  */
  29 function sqimap_session_id($unique_id = FALSE) {
  30     static $sqimap_session_id = 1;
  31
  32     if (!$unique_id) {
  33         return( sprintf("A%03d", $sqimap_session_id++) );
  34     } else {
  35         return( sprintf("A%03d", $sqimap_session_id++) . ' UID' );
  36     }
  37 }
  38
  39 /**
  40  * Both send a command and accept the result from the command.
  41  * This is to allow proper session number handling.
  42  * @param stream $imap_stream imap connection resource
  43  * @param string $query imap command
  44  * @param boolean $handle_errors see sqimap_retrieve_imap_response()
  45  * @param array $response
  46  * @param array $message
  47  * @param boolean $unique_id (since 1.3.0) see sqimap_session_id().
  48  * @return mixed returns false on imap error. displays error message
  49  *  if imap stream is not available.
  50  * @since 1.2.3
  51  */
  52 function sqimap_run_command_list ($imap_stream, $query, $handle_errors, &$response, &$message, $unique_id = false) {
  53     if ($imap_stream) {
  54         $sid = sqimap_session_id($unique_id);
  55         fputs ($imap_stream, $sid . ' ' . $query . "\r\n");
  56         $tag_uid_a = explode(' ',trim($sid));
  57         $tag = $tag_uid_a[0];
  58         $read = sqimap_retrieve_imap_response ($imap_stream, $tag, $handle_errors, $response, $message, $query );
  59         /* get the response and the message */
  60         $message = $message[$tag];
  61         $response = $response[$tag];
  62         return $read[$tag];
  63     } else {
  64         global $squirrelmail_language, $color;
  65         set_up_language($squirrelmail_language);
  66         $string = "<b><font color=\"$color[2]\">\n" .
  67                 _("ERROR: No available IMAP stream.") .
  68                 "</b></font>\n";
  69         error_box($string);
  70         return false;
  71     }
  72 }
  73
  74 /**
  75  * @param stream $imap_stream imap connection resource
  76  * @param string $query imap command
  77  * @param boolean $handle_errors see sqimap_retrieve_imap_response()
  78  * @param array $response empty string, if return = false
  79  * @param array $message empty string, if return = false
  80  * @param boolean $unique_id (since 1.3.0) see sqimap_session_id()
  81  * @param boolean $filter (since 1.4.1 and 1.5.0) see sqimap_fread()
  82  * @param mixed $outputstream (since 1.4.1 and 1.5.0) see sqimap_fread()
  83  * @param boolean $no_return (since 1.4.1 and 1.5.0) see sqimap_fread()
  84  * @return mixed returns false on imap error. displays error message
  85  *  if imap stream is not available.
  86  * @since 1.2.3
  87  */
  88 function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response,
  89                             &$message, $unique_id = false,$filter=false,
  90                              $outputstream=false,$no_return=false) {
  91     if ($imap_stream) {
  92         $sid = sqimap_session_id($unique_id);
  93         fputs ($imap_stream, $sid . ' ' . $query . "\r\n");
  94         $tag_uid_a = explode(' ',trim($sid));
  95         $tag = $tag_uid_a[0];
  96
  97         $read = sqimap_read_data ($imap_stream, $tag, $handle_errors, $response,
  98                                   $message, $query,$filter,$outputstream,$no_return);
  99         if (empty($read)) {    //IMAP server dropped its connection
 100             $response = '';
 101             $message = '';
 102             return false;
 103         }
 104         /* retrieve the response and the message */
 105         $response = $response[$tag];
 106         $message  = $message[$tag];
 107
 108         if (!empty($read[$tag])) {
 109             return $read[$tag][0];
 110         } else {
 111             return $read[$tag];
 112         }
 113     } else {
 114         global $squirrelmail_language, $color;
 115         set_up_language($squirrelmail_language);
 116         $string = "<b><font color=\"$color[2]\">\n" .
 117                 _("ERROR: No available IMAP stream.") .
 118                 "</b></font>\n";
 119         error_box($string);
 120         return false;
 121     }
 122 }
 123
 124 /**
 125  * @param mixed $new_query
 126  * @param string $tag
 127  * @param array $aQuery
 128  * @param boolean $unique_id see sqimap_session_id()
 129  * @since 1.5.0
 130  */
 131 function sqimap_prepare_pipelined_query($new_query,&$tag,&$aQuery,$unique_id) {
 132     $sid = sqimap_session_id($unique_id);
 133     $tag_uid_a = explode(' ',trim($sid));
 134     $tag = $tag_uid_a[0];
 135     $query = $sid . ' '.$new_query."\r\n";
 136     $aQuery[$tag] = $query;
 137 }
 138
 139 /**
 140  * @param stream $imap_stream imap stream
 141  * @param array $aQueryList
 142  * @param boolean $handle_errors
 143  * @param array $aServerResponse
 144  * @param array $aServerMessage
 145  * @param boolean $unique_id see sqimap_session_id()
 146  * @param boolean $filter see sqimap_fread()
 147  * @param mixed $outputstream see sqimap_fread()
 148  * @param boolean $no_return see sqimap_fread()
 149  * @since 1.5.0
 150  */
 151 function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors,
 152                        &$aServerResponse, &$aServerMessage, $unique_id = false,
 153                        $filter=false,$outputstream=false,$no_return=false) {
 154     $aResponse = false;
 155
 156     /*
 157        Do not fire all calls at once to the IMAP server but split the calls up
 158        in portions of $iChunkSize. If we do not do that I think we misbehave as
 159        IMAP client or should handle BYE calls if the IMAP server drops the
 160        connection because the number of queries is to large. This isn't tested
 161        but a wild guess how it could work in the field.
 162
 163        After testing it on Exchange 2000 we discovered that a chunksize of 32
 164        was quicker then when we raised it to 128.
 165     */
 166     $iQueryCount = count($aQueryList);
 167     $iChunkSize = 32;
 168     // array_chunk would also do the job but it's supported from php > 4.2
 169     $aQueryChunks = array();
 170     $iLoops = floor($iQueryCount / $iChunkSize);
 171
 172     if ($iLoops * $iChunkSize != $iQueryCount) ++$iLoops;
 173
 174     if (!function_exists('array_chunk')) { // arraychunk replacement
 175         reset($aQueryList);
 176         for($i=0;$i<$iLoops;++$i) {
 177             for($j=0;$j<$iChunkSize;++$j) {
 178                 $key = key($aQueryList);
 179                 $aTmp[$key] = $aQueryList[$key];
 180                 if (next($aQueryList) === false) break;
 181             }
 182             $aQueryChunks[] = $aTmp;
 183         }
 184     } else {
 185         $aQueryChunks = array_chunk($aQueryList,$iChunkSize,true);
 186     }
 187
 188     for ($i=0;$i<$iLoops;++$i) {
 189         $aQuery = $aQueryChunks[$i];
 190         foreach($aQuery as $tag => $query) {
 191             fputs($imap_stream,$query);
 192             $aResults[$tag] = false;
 193         }
 194         foreach($aQuery as $tag => $query) {
 195             if ($aResults[$tag] == false) {
 196                 $aReturnedResponse = sqimap_retrieve_imap_response ($imap_stream, $tag,
 197                                     $handle_errors, $response, $message, $query,
 198                                     $filter,$outputstream,$no_return);
 199                 foreach ($aReturnedResponse as $returned_tag => $aResponse) {
 200                     if (!empty($aResponse)) {
 201                         $aResults[$returned_tag] = $aResponse[0];
 202                     } else {
 203                         $aResults[$returned_tag] = $aResponse;
 204                     }
 205                     $aServerResponse[$returned_tag] = $response[$returned_tag];
 206                     $aServerMessage[$returned_tag] = $message[$returned_tag];
 207                 }
 208             }
 209         }
 210     }
 211     return $aResults;
 212 }
 213
 214 /**
 215  * Custom fgets function: gets a line from the IMAP server,
 216  * no matter how big it may be.
 217  * @param stream $imap_stream the stream to read from
 218  * @return string a line
 219  * @since 1.2.8
 220  */
 221 function sqimap_fgets($imap_stream) {
 222     $read = '';
 223     $buffer = 4096;
 224     $results = '';
 225     $offset = 0;
 226     while (strpos($results, "\r\n", $offset) === false) {
 227         if (!($read = fgets($imap_stream, $buffer))) {
 228         /* this happens in case of an error */
 229         /* reset $results because it's useless */
 230         $results = false;
 231             break;
 232         }
 233         if ( $results != '' ) {
 234             $offset = strlen($results) - 1;
 235         }
 236         $results .= $read;
 237     }
 238     return $results;
 239 }
 240
 241 /**
 242  * @param stream $imap_stream
 243  * @param integer $iSize
 244  * @param boolean $filter
 245  * @param mixed $outputstream stream or 'php://stdout' string
 246  * @param boolean $no_return controls data returned by function
 247  * @return string
 248  * @since 1.4.1
 249  */
 250 function sqimap_fread($imap_stream,$iSize,$filter=false,
 251                       $outputstream=false, $no_return=false) {
 252     if (!$filter || !$outputstream) {
 253         $iBufferSize = $iSize;
 254     } else {
 255         // see php bug 24033. They changed fread behaviour %$^&$%
 256         $iBufferSize = 7800; // multiple of 78 in case of base64 decoding.
 257     }
 258     if ($iSize < $iBufferSize) {
 259         $iBufferSize = $iSize;
 260     }
 261
 262     $iRetrieved = 0;
 263     $results = '';
 264     $sRead = $sReadRem = '';
 265     // NB: fread can also stop at end of a packet on sockets.
 266     while ($iRetrieved < $iSize) {
 267         $sRead = fread($imap_stream,$iBufferSize);
 268         $iLength = strlen($sRead);
 269         $iRetrieved += $iLength ;
 270         $iRemaining = $iSize - $iRetrieved;
 271         if ($iRemaining < $iBufferSize) {
 272             $iBufferSize = $iRemaining;
 273         }
 274         if ($sRead == '') {
 275             $results = false;
 276             break;
 277         }
 278         if ($sReadRem != '') {
 279             $sRead = $sReadRem . $sRead;
 280             $sReadRem = '';
 281         }
 282
 283         if ($filter && $sRead != '') {
 284            // in case the filter is base64 decoding we return a remainder
 285            $sReadRem = $filter($sRead);
 286         }
 287         if ($outputstream && $sRead != '') {
 288            if (is_resource($outputstream)) {
 289                fwrite($outputstream,$sRead);
 290            } else if ($outputstream == 'php://stdout') {
 291                echo $sRead;
 292            }
 293         }
 294         if ($no_return) {
 295             $sRead = '';
 296         } else {
 297             $results .= $sRead;
 298         }
 299     }
 300     return $results;
 301 }
 302
 303
 304 /**
 305  * Obsolete function, inform plugins that use it
 306  * @param stream $imap_stream
 307  * @param string $tag
 308  * @param boolean $handle_errors
 309  * @param array $response
 310  * @param array $message
 311  * @param string $query
 312  * @since 1.1.3
 313  * @deprecated (since 1.5.0) use sqimap_run_command or sqimap_run_command_list instead
 314  */
 315 function sqimap_read_data_list($imap_stream, $tag, $handle_errors,
 316           &$response, &$message, $query = '') {
 317     global $color, $oTemplate, $squirrelmail_language;
 318     set_up_language($squirrelmail_language);
 319     $string = "<b><font color=\"$color[2]\">\n" .
 320         _("ERROR: Bad function call.") .
 321         "</b><br />\n" .
 322         _("Reason:") . ' '.
 323           'There is a plugin installed which make use of the  <br />' .
 324           'SquirrelMail internal function sqimap_read_data_list.<br />'.
 325           'Please adapt the installed plugin and let it use<br />'.
 326           'sqimap_run_command or sqimap_run_command_list instead<br /><br />'.
 327           'The following query was issued:<br />'.
 328            htmlspecialchars($query) . '<br />' . "</font><br />\n";
 329     error_box($string);
 330     $oTemplate->display('footer.tpl');
 331     exit;
 332 }
 333
 334 /**
 335  * Function to display an error related to an IMAP query.
 336  * @param string title the caption of the error box
 337  * @param string query the query that went wrong
 338  * @param string message_title optional message title
 339  * @param string message optional error message
 340  * @param string $link an optional link to try again
 341  * @return void
 342  * @since 1.5.0
 343  */
 344 function sqimap_error_box($title, $query = '', $message_title = '', $message = '', $link = '')
 345 {
 346     global $color, $squirrelmail_language;
 347
 348     set_up_language($squirrelmail_language);
 349     $string = "<font color=\"$color[2]\"><b>\n" . $title . "</b><br />\n";
 350     $cmd = explode(' ',$query);
 351     $cmd= strtolower($cmd[0]);
 352
 353     if ($query != '' &&  $cmd != 'login')
 354         $string .= _("Query:") . ' ' . htmlspecialchars($query) . '<br />';
 355     if ($message_title != '')
 356         $string .= $message_title;
 357     if ($message != '')
 358         $string .= htmlspecialchars($message);
 359     $string .= "</font><br />\n";
 360     if ($link != '')
 361         $string .= $link;
 362     error_box($string);
 363 }
 364
 365 /**
 366  * Reads the output from the IMAP stream.  If handle_errors is set to true,
 367  * this will also handle all errors that are received.  If it is not set,
 368  * the errors will be sent back through $response and $message.
 369  * @param stream $imap_stream imap stream
 370  * @param string $tag
 371  * @param boolean $handle_errors handle errors internally or send them in $response and $message.
 372  * @param array $response
 373  * @param array $message
 374  * @param string $query command that can be printed if something fails
 375  * @param boolean $filter see sqimap_fread()
 376  * @param mixed $outputstream  see sqimap_fread()
 377  * @param boolean $no_return  see sqimap_fread()
 378  * @since 1.5.0
 379  */
 380 function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
 381           &$response, &$message, $query = '',
 382            $filter = false, $outputstream = false, $no_return = false) {
 383     global $color, $squirrelmail_language;
 384     $read = '';
 385     if (!is_array($message)) $message = array();
 386     if (!is_array($response)) $response = array();
 387     $aResponse = '';
 388     $resultlist = array();
 389     $data = array();
 390     $sCommand = '';
 391     if (preg_match("/^(\w+)\s*/",$query,$aMatch)) {
 392         $sCommand = strtoupper($aMatch[1]);
 393     } else {
 394         // error reporting (shouldn't happen)
 395     }
 396     $read = sqimap_fgets($imap_stream);
 397     $i = 0;
 398     while ($read) {
 399         $char = $read{0};
 400         switch ($char)
 401         {
 402           case '+':
 403           default:
 404             $read = sqimap_fgets($imap_stream);
 405             break;
 406
 407           case $tag{0}:
 408           {
 409             /* get the command */
 410             $arg = '';
 411             $i = strlen($tag)+1;
 412             $s = substr($read,$i);
 413             if (($j = strpos($s,' ')) || ($j = strpos($s,"\n"))) {
 414                 $arg = substr($s,0,$j);
 415             }
 416             $found_tag = substr($read,0,$i-1);
 417             if ($found_tag) {
 418                 switch ($arg)
 419                 {
 420                   case 'OK':
 421                   case 'BAD':
 422                   case 'NO':
 423                   case 'BYE':
 424                   case 'PREAUTH':
 425                     $response[$found_tag] = $arg;
 426                     $message[$found_tag] = trim(substr($read,$i+strlen($arg)));
 427                     if (!empty($data)) {
 428                         $resultlist[] = $data;
 429                     }
 430                     $aResponse[$found_tag] = $resultlist;
 431                     $data = $resultlist = array();
 432                     if ($found_tag == $tag) {
 433                         break 3; /* switch switch while */
 434                     }
 435                   break;
 436                   default:
 437                     /* this shouldn't happen */
 438                     $response[$found_tag] = $arg;
 439                     $message[$found_tag] = trim(substr($read,$i+strlen($arg)));
 440                     if (!empty($data)) {
 441                         $resultlist[] = $data;
 442                     }
 443                     $aResponse[$found_tag] = $resultlist;
 444                     $data = $resultlist = array();
 445                     if ($found_tag == $tag) {
 446                         break 3; /* switch switch while */
 447                     }
 448                 }
 449             }
 450             $read = sqimap_fgets($imap_stream);
 451             if ($read === false) { /* error */
 452                  break 2; /* switch while */
 453             }
 454             break;
 455           } // end case $tag{0}
 456
 457           case '*':
 458           {
 459             if (($sCommand == "FETCH" || $sCommand == "STORE")  && preg_match('/^\*\s\d+\sFETCH/',$read)) {
 460                 /* check for literal */
 461                 $s = substr($read,-3);
 462                 $fetch_data = array();
 463                 do { /* outer loop, continue until next untagged fetch
 464                         or tagged reponse */
 465                     do { /* innerloop for fetching literals. with this loop
 466                             we prohibid that literal responses appear in the
 467                             outer loop so we can trust the untagged and
 468                             tagged info provided by $read */
 469                         $read_literal = false;
 470                         if ($s === "}\r\n") {
 471                             $j = strrpos($read,'{');
 472                             $iLit = substr($read,$j+1,-3);
 473                             $fetch_data[] = $read;
 474                             $sLiteral = sqimap_fread($imap_stream,$iLit,$filter,$outputstream,$no_return);
 475                             if ($sLiteral === false) { /* error */
 476                                 break 4; /* while while switch while */
 477                             }
 478                             /* backwards compattibility */
 479                             $aLiteral = explode("\n", $sLiteral);
 480                             /* release not neaded data */
 481                             unset($sLiteral);
 482                             foreach ($aLiteral as $line) {
 483                                 $fetch_data[] = $line ."\n";
 484                             }
 485                             /* release not neaded data */
 486                             unset($aLiteral);
 487                             /* next fgets belongs to this fetch because
 488                                we just got the exact literalsize and there
 489                                must follow data to complete the response */
 490                             $read = sqimap_fgets($imap_stream);
 491                             if ($read === false) { /* error */
 492                                 break 4; /* while while switch while */
 493                             }
 494                             $s = substr($read,-3);
 495                             $read_literal = true;
 496                             continue;
 497                         } else {
 498                             $fetch_data[] = $read;
 499                         }
 500                         /* retrieve next line and check in the while
 501                            statements if it belongs to this fetch response */
 502                         $read = sqimap_fgets($imap_stream);
 503                         if ($read === false) { /* error */
 504                             break 4; /* while while switch while */
 505                         }
 506                         /* check for next untagged reponse and break */
 507                         if ($read{0} == '*') break 2;
 508                         $s = substr($read,-3);
 509                     } while ($s === "}\r\n" || $read_literal);
 510                     $s = substr($read,-3);
 511                 } while ($read{0} !== '*' &&
 512                          substr($read,0,strlen($tag)) !== $tag);
 513                 $resultlist[] = $fetch_data;
 514                 /* release not neaded data */
 515                 unset ($fetch_data);
 516             } else {
 517                 $s = substr($read,-3);
 518                 do {
 519                     if ($s === "}\r\n") {
 520                         $j = strrpos($read,'{');
 521                         $iLit = substr($read,$j+1,-3);
 522                         // check for numeric value to avoid that untagged responses like:
 523                         // * OK [PARSE] Unexpected characters at end of address: {SET:debug=51}
 524                         // will trigger literal fetching  ({SET:debug=51} !== int )
 525                         if (is_numeric($iLit)) {
 526                             $data[] = $read;
 527                             $sLiteral = fread($imap_stream,$iLit);
 528                             if ($sLiteral === false) { /* error */
 529                                 $read = false;
 530                                 break 3; /* while switch while */
 531                             }
 532                             $data[] = $sLiteral;
 533                             $data[] = sqimap_fgets($imap_stream);
 534                         } else {
 535                             $data[] = $read;
 536                         }
 537                     } else {
 538                          $data[] = $read;
 539                     }
 540                     $read = sqimap_fgets($imap_stream);
 541                     if ($read === false) {
 542                         break 3; /* while switch while */
 543                     } else if ($read{0} == '*') {
 544                         break;
 545                     }
 546                     $s = substr($read,-3);
 547                 } while ($s === "}\r\n");
 548                 break 1;
 549             }
 550             break;
 551           } // end case '*'
 552         }   // end switch
 553     } // end while
 554
 555     /* error processing in case $read is false */
 556     if ($read === false) {
 557         // try to retrieve an untagged bye respons from the results
 558         $sResponse = array_pop($data);
 559         if ($sResponse !== NULL && strpos($sResponse,'* BYE') !== false) {
 560             if (!$handle_errors) {
 561                 $query = '';
 562             }
 563             sqimap_error_box(_("ERROR: IMAP server closed the connection."), $query, _("Server responded:"),$sResponse);
 564             echo '</body></html>';
 565             exit;
 566         } else if ($handle_errors) {
 567             unset($data);
 568             sqimap_error_box(_("ERROR: Connection dropped by IMAP server."), $query);
 569             exit;
 570         }
 571     }
 572
 573     /* Set $resultlist array */
 574     if (!empty($data)) {
 575         //$resultlist[] = $data;
 576     }
 577     elseif (empty($resultlist)) {
 578         $resultlist[] = array();
 579     }
 580
 581     /* Return result or handle errors */
 582     if ($handle_errors == false) {
 583         return $aResponse;
 584     }
 585     switch ($response[$tag]) {
 586     case 'OK':
 587         return $aResponse;
 588         break;
 589     case 'NO':
 590         /* ignore this error from M$ exchange, it is not fatal (aka bug) */
 591         if (strstr($message[$tag], 'command resulted in') === false) {
 592             sqimap_error_box(_("ERROR: Could not complete request."), $query, _("Reason Given:") . ' ', $message[$tag]);
 593             echo '</body></html>';
 594             exit;
 595         }
 596         break;
 597     case 'BAD':
 598         sqimap_error_box(_("ERROR: Bad or malformed request."), $query, _("Server responded:") . ' ', $message[$tag]);
 599         echo '</body></html>';
 600         exit;
 601     case 'BYE':
 602         sqimap_error_box(_("ERROR: IMAP server closed the connection."), $query, _("Server responded:") . ' ', $message[$tag]);
 603         echo '</body></html>';
 604         exit;
 605     default:
 606         sqimap_error_box(_("ERROR: Unknown IMAP response."), $query, _("Server responded:") . ' ', $message[$tag]);
 607        /* the error is displayed but because we don't know the reponse we
 608           return the result anyway */
 609        return $aResponse;
 610        break;
 611     }
 612 }
 613
 614 /**
 615  * @param stream $imap_stream imap string
 616  * @param string $tag_uid
 617  * @param boolean $handle_errors
 618  * @param array $response
 619  * @param array $message
 620  * @param string $query (since 1.2.5)
 621  * @param boolean $filter (since 1.4.1) see sqimap_fread()
 622  * @param mixed $outputstream (since 1.4.1) see sqimap_fread()
 623  * @param boolean $no_return (since 1.4.1) see sqimap_fread()
 624  */
 625 function sqimap_read_data ($imap_stream, $tag_uid, $handle_errors,
 626                            &$response, &$message, $query = '',
 627                            $filter=false,$outputstream=false,$no_return=false) {
 628
 629     $tag_uid_a = explode(' ',trim($tag_uid));
 630     $tag = $tag_uid_a[0];
 631
 632     $res = sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors,
 633               $response, $message, $query,$filter,$outputstream,$no_return);
 634     return $res;
 635 }
 636
 637 /**
 638  * Connects to the IMAP server and returns a resource identifier for use with
 639  * the other SquirrelMail IMAP functions. Does NOT login!
 640  * @param string server hostname of IMAP server
 641  * @param int port port number to connect to
 642  * @param integer $tls whether to use plain text(0), TLS(1) or STARTTLS(2) when connecting.
 643  *  Argument was boolean before 1.5.1.
 644  * @return imap-stream resource identifier
 645  * @since 1.5.0 (usable only in 1.5.1 or later)
 646  */
 647 function sqimap_create_stream($server,$port,$tls=0) {
 648     global $squirrelmail_language;
 649
 650     if (strstr($server,':') && ! preg_match("/^\[.*\]$/",$server)) {
 651         // numerical IPv6 address must be enclosed in square brackets
 652         $server = '['.$server.']';
 653     }
 654
 655     if ($tls == 1) {
 656         if ((check_php_version(4,3)) and (extension_loaded('openssl'))) {
 657             /* Use TLS by prefixing "tls://" to the hostname */
 658             $server = 'tls://' . $server;
 659         } else {
 660             require_once(SM_PATH . 'functions/display_messages.php');
 661             logout_error( sprintf(_("Error connecting to IMAP server: %s."), $server).
 662                 '<br />'.
 663                 _("TLS is enabled, but this version of PHP does not support TLS sockets, or is missing the openssl extension.").
 664                 '<br /><br />'.
 665                 _("Please contact your system administrator and report this error."),
 666                           sprintf(_("Error connecting to IMAP server: %s."), $server));
 667         }
 668     }
 669
 670     $imap_stream = @fsockopen($server, $port, $error_number, $error_string, 15);
 671
 672     /* Do some error correction */
 673     if (!$imap_stream) {
 674         set_up_language($squirrelmail_language, true);
 675         require_once(SM_PATH . 'functions/display_messages.php');
 676         logout_error( sprintf(_("Error connecting to IMAP server: %s."), $server).
 677             "<br />\r\n$error_number : $error_string<br />\r\n",
 678                       sprintf(_("Error connecting to IMAP server: %s."), $server) );
 679         exit;
 680     }
 681     $server_info = fgets ($imap_stream, 1024);
 682
 683     /**
 684      * Implementing IMAP STARTTLS (rfc2595) in php 5.1.0+
 685      * http://www.php.net/stream-socket-enable-crypto
 686      */
 687     if ($tls === 2) {
 688         if (function_exists('stream_socket_enable_crypto')) {
 689             // check starttls capability, don't use cached capability version
 690             if (! sqimap_capability($imap_stream, 'STARTTLS', false)) {
 691                 // imap server does not declare starttls support
 692                 sqimap_error_box(sprintf(_("Error connecting to IMAP server: %s."), $server),
 693                                  '','',
 694                                  _("IMAP STARTTLS is enabled in SquirrelMail configuration, but used IMAP server does not support STARTTLS."));
 695                 exit;
 696             }
 697
 698             // issue starttls command and check response
 699             sqimap_run_command($imap_stream, 'STARTTLS', false, $starttls_response, $starttls_message);
 700             // check response
 701             if ($starttls_response!='OK') {
 702                 // starttls command failed
 703                 sqimap_error_box(sprintf(_("Error connecting to IMAP server: %s."), $server),
 704                                  'STARTTLS',
 705                                  _("Server replied:") . ' ',
 706                                  $starttls_message);
 707                 exit();
 708             }
 709
 710             // start crypto on connection. suppress function errors.
 711             if (@stream_socket_enable_crypto($imap_stream,true,STREAM_CRYPTO_METHOD_TLS_CLIENT)) {
 712                 // starttls was successful
 713
 714                 /**
 715                  * RFC 2595 requires to discard CAPABILITY information after successful
 716                  * STARTTLS command. We don't follow RFC, because SquirrelMail stores CAPABILITY
 717                  * information only after successful login (src/redirect.php) and cached information
 718                  * is used only in other php script connections after successful STARTTLS. If script
 719                  * issues sqimap_capability() call before sqimap_login() and wants to get initial
 720                  * capability response, script should set third sqimap_capability() argument to false.
 721                  */
 722                 //sqsession_unregister('sqimap_capabilities');
 723             } else {
 724                 /**
 725                  * stream_socket_enable_crypto() call failed. Possible issues:
 726                  * - broken ssl certificate (uw drops connection, error is in syslog mail facility)
 727                  * - some ssl error (can reproduce with STREAM_CRYPTO_METHOD_SSLv3_CLIENT, PHP E_WARNING
 728                  *   suppressed in stream_socket_enable_crypto() call)
 729                  */
 730                 sqimap_error_box(sprintf(_("Error connecting to IMAP server: %s."), $server),
 731                                  '','',
 732                                  _("Unable to start TLS."));
 733                 /**
 734                  * Bug: stream_socket_enable_crypto() does not register SSL errors in
 735                  * openssl_error_string() or stream notification wrapper and displays
 736                  * them in E_WARNING level message. It is impossible to retrieve error
 737                  * message without own error handler.
 738                  */
 739                 exit;
 740             }
 741         } else {
 742             // php install does not support stream_socket_enable_crypto() function
 743             sqimap_error_box(sprintf(_("Error connecting to IMAP server: %s."), $server),
 744                              '','',
 745                              _("IMAP STARTTLS is enabled in SquirrelMail configuration, but used PHP version does not support functions that allow to enable encryption on open socket."));
 746             exit;
 747         }
 748     }
 749     return $imap_stream;
 750 }
 751
 752 /**
 753  * Logs the user into the IMAP server.  If $hide is set, no error messages
 754  * will be displayed (if set to 1, just exits, if set to 2, returns FALSE).
 755  * This function returns the IMAP connection handle.
 756  * @param string $username user name
 757  * @param string $password password encrypted with onetimepad. Since 1.5.2
 758  *  function can use internal password functions, if parameter is set to
 759  *  boolean false.
 760  * @param string $imap_server_address address of imap server
 761  * @param integer $imap_port port of imap server
 762  * @param int $hide controls display connection errors:
 763  *                  0 = do not hide
 764  *                  1 = show no errors (just exit)
 765  *                  2 = show no errors (return FALSE)
 766  *                  3 = show no errors (return error string)
 767  * @return mixed The IMAP connection stream, or if the connection fails,
 768  *               FALSE if $hide is set to 2 or an error string if $hide
 769  *               is set to 3.
 770  */
 771 function sqimap_login ($username, $password, $imap_server_address, $imap_port, $hide) {
 772     global $color, $squirrelmail_language, $onetimepad, $use_imap_tls,
 773            $imap_auth_mech, $sqimap_capabilities;
 774
 775     // Note/TODO: This hack grabs the $authz argument from the session. In the short future,
 776     // a new argument in function sqimap_login() will be used instead.
 777     $authz = '';
 778     global $authz;
 779     sqgetglobalvar('authz' , $authz , SQ_SESSION);
 780
 781     if(!empty($authz)) {
 782         /* authz plugin - specific:
 783          * Get proxy login parameters from authz plugin configuration. If they
 784          * exist, they will override the current ones.
 785          * This is useful if we want to use different SASL authentication mechanism
 786          * and/or different TLS settings for proxy logins. */
 787         global $authz_imap_auth_mech, $authz_use_imap_tls, $authz_imapPort_tls;
 788         $imap_auth_mech = !empty($authz_imap_auth_mech) ? strtolower($authz_imap_auth_mech) : $imap_auth_mech;
 789         $use_imap_tls = !empty($authz_use_imap_tls)? $authz_use_imap_tls : $use_imap_tls;
 790         $imap_port = !empty($authz_use_imap_tls)? $authz_imapPort_tls : $imap_port;
 791
 792         if($imap_auth_mech == 'login' || $imap_auth_mech == 'cram-md5') {
 793             logout_error("Misconfigured Plugin (authz or equivalent):<br/>".
 794             "The LOGIN and CRAM-MD5 authentication mechanisms cannot be used when attempting proxy login.");
 795             exit;
 796         }
 797     }
 798
 799     /* get imap login password */
 800     if ($password===false) {
 801         /* standard functions */
 802         $password = sqauth_read_password();
 803     } else {
 804         /* old way. $key must be extracted from cookie */
 805         if (!isset($onetimepad) || empty($onetimepad)) {
 806             sqgetglobalvar('onetimepad' , $onetimepad , SQ_SESSION );
 807         }
 808         /* Decrypt the password */
 809         $password = OneTimePadDecrypt($password, $onetimepad);
 810     }
 811
 812     if (!isset($sqimap_capabilities)) {
 813         sqgetglobalvar('sqimap_capabilities' , $sqimap_capabilities , SQ_SESSION );
 814     }
 815
 816     $host = $imap_server_address;
 817     $imap_server_address = sqimap_get_user_server($imap_server_address, $username);
 818
 819     $imap_stream = sqimap_create_stream($imap_server_address,$imap_port,$use_imap_tls);
 820
 821     if (($imap_auth_mech == 'cram-md5') OR ($imap_auth_mech == 'digest-md5')) {
 822         // We're using some sort of authentication OTHER than plain or login
 823         $tag=sqimap_session_id(false);
 824         if ($imap_auth_mech == 'digest-md5') {
 825             $query = $tag . " AUTHENTICATE DIGEST-MD5\r\n";
 826         } elseif ($imap_auth_mech == 'cram-md5') {
 827             $query = $tag . " AUTHENTICATE CRAM-MD5\r\n";
 828         }
 829         fputs($imap_stream,$query);
 830         $answer=sqimap_fgets($imap_stream);
 831         // Trim the "+ " off the front
 832         $response=explode(" ",$answer,3);
 833         if ($response[0] == '+') {
 834             // Got a challenge back
 835             $challenge=$response[1];
 836             if ($imap_auth_mech == 'digest-md5') {
 837                 $reply = digest_md5_response($username,$password,$challenge,'imap',$host,$authz);
 838             } elseif ($imap_auth_mech == 'cram-md5') {
 839                 $reply = cram_md5_response($username,$password,$challenge);
 840             }
 841             fputs($imap_stream,$reply);
 842             $read=sqimap_fgets($imap_stream);
 843             if ($imap_auth_mech == 'digest-md5') {
 844                 // DIGEST-MD5 has an extra step..
 845                 if (substr($read,0,1) == '+') { // OK so far..
 846                     fputs($imap_stream,"\r\n");
 847                     $read=sqimap_fgets($imap_stream);
 848                 }
 849             }
 850             $results=explode(" ",$read,3);
 851             $response=$results[1];
 852             $message=$results[2];
 853         } else {
 854             // Fake the response, so the error trap at the bottom will work
 855             $response="BAD";
 856             $message='IMAP server does not appear to support the authentication method selected.';
 857             $message .= '  Please contact your system administrator.';
 858         }
 859     } elseif ($imap_auth_mech == 'login') {
 860     // Original IMAP login code
 861         $query = 'LOGIN "' . quoteimap($username) .  '" "' . quoteimap($password) . '"';
 862         $read = sqimap_run_command ($imap_stream, $query, false, $response, $message);
 863     } elseif ($imap_auth_mech == 'plain') {
 864         /***
 865          * SASL PLAIN, RFC 4616 (updates 2595)
 866          *
 867          * The mechanism consists of a single message, a string of [UTF-8]
 868          * encoded [Unicode] characters, from the client to the server.  The
 869          * client presents the authorization identity (identity to act as),
 870          * followed by a NUL (U+0000) character, followed by the authentication
 871          * identity (identity whose password will be used), followed by a NUL
 872          * (U+0000) character, followed by the clear-text password.  As with
 873          * other SASL mechanisms, the client does not provide an authorization
 874          * identity when it wishes the server to derive an identity from the
 875          * credentials and use that as the authorization identity.
 876          */
 877         $tag=sqimap_session_id(false);
 878         $sasl = (isset($sqimap_capabilities['SASL-IR']) && $sqimap_capabilities['SASL-IR']) ? true : false;
 879         if(!empty($authz)) {
 880             $auth = base64_encode("$username\0$authz\0$password");
 881         } else {
 882             $auth = base64_encode("$username\0$username\0$password");
 883         }
 884         if ($sasl) {
 885             // IMAP Extension for SASL Initial Client Response
 886             // <draft-siemborski-imap-sasl-initial-response-01b.txt>
 887             $query = $tag . " AUTHENTICATE PLAIN $auth\r\n";
 888             fputs($imap_stream, $query);
 889             $read = sqimap_fgets($imap_stream);
 890         } else {
 891             $query = $tag . " AUTHENTICATE PLAIN\r\n";
 892             fputs($imap_stream, $query);
 893             $read=sqimap_fgets($imap_stream);
 894             if (substr($read,0,1) == '+') { // OK so far..
 895                 fputs($imap_stream, "$auth\r\n");
 896                 $read = sqimap_fgets($imap_stream);
 897             }
 898         }
 899         $results=explode(" ",$read,3);
 900         $response=$results[1];
 901         $message=$results[2];
 902
 903     } else {
 904         $response="BAD";
 905         $message="Internal SquirrelMail error - unknown IMAP authentication method chosen.  Please contact the developers.";
 906     }
 907
 908     /* If the connection was not successful, lets see why */
 909     if ($response != 'OK') {
 910         if (!$hide || $hide == 3) {
 911 //FIXME: UUURG... We don't want HTML in error messages, should also do html sanitizing of error messages elsewhere; should't assume output is destined for an HTML browser here
 912             if ($response != 'NO') {
 913                 /* "BAD" and anything else gets reported here. */
 914                 $message = htmlspecialchars($message);
 915                 set_up_language($squirrelmail_language, true);
 916                 if ($response == 'BAD') {
 917                     if ($hide == 3) return sprintf(_("Bad request: %s"), $message);
 918                     $string = sprintf (_("Bad request: %s")."<br />\r\n", $message);
 919                 } else {
 920                     if ($hide == 3) return sprintf(_("Unknown error: %s"), $message);
 921                     $string = sprintf (_("Unknown error: %s") . "<br />\n", $message);
 922                 }
 923                 if (isset($read) && is_array($read)) {
 924                     $string .= '<br />' . _("Read data:") . "<br />\n";
 925                     foreach ($read as $line) {
 926                         $string .= htmlspecialchars($line) . "<br />\n";
 927                     }
 928                 }
 929                 error_box($string);
 930                 exit;
 931             } else {
 932                 /*
 933                  * If the user does not log in with the correct
 934                  * username and password it is not possible to get the
 935                  * correct locale from the user's preferences.
 936                  * Therefore, apply the same hack as on the login
 937                  * screen.
 938                  *
 939                  * $squirrelmail_language is set by a cookie when
 940                  * the user selects language and logs out
 941                  */
 942
 943                 set_up_language($squirrelmail_language, true);
 944                 sqsession_destroy();
 945
 946                 /* terminate the session nicely */
 947                 sqimap_logout($imap_stream);
 948                 if ($hide == 3) return _("Unknown user or password incorrect.");
 949                 logout_error( _("Unknown user or password incorrect.") );
 950                 exit;
 951             }
 952         } else {
 953             if ($hide == 2) return FALSE;
 954             exit;
 955         }
 956     }
 957
 958     /* Special error case:
 959      * Login referrals. The server returns:
 960      * ? OK [REFERRAL <imap url>]
 961      * Check RFC 2221 for details. Since we do not support login referrals yet
 962      * we log the user out.
 963      */
 964     if ( stristr($message, 'REFERRAL imap') === TRUE ) {
 965         sqimap_logout($imap_stream);
 966         set_up_language($squirrelmail_language, true);
 967         sqsession_destroy();
 968         logout_error( _("Your mailbox is not located at this server. Try a different server or consult your system administrator") );
 969         exit;
 970     }
 971
 972     return $imap_stream;
 973 }
 974
 975 /**
 976  * Simply logs out the IMAP session
 977  * @param stream $imap_stream the IMAP connection to log out.
 978  * @return void
 979  */
 980 function sqimap_logout ($imap_stream) {
 981     /* Logout is not valid until the server returns 'BYE'
 982      * If we don't have an imap_ stream we're already logged out */
 983     if(isset($imap_stream) && $imap_stream)
 984         sqimap_run_command($imap_stream, 'LOGOUT', false, $response, $message);
 985 }
 986
 987 /**
 988  * Retrieve the CAPABILITY string from the IMAP server.
 989  * If capability is set, returns only that specific capability,
 990  * else returns array of all capabilities.
 991  * @param stream $imap_stream
 992  * @param string $capability (since 1.3.0)
 993  * @param boolean $bUseCache (since 1.5.1) Controls use of capability data stored in session
 994  * @return mixed (string if $capability is set and found,
 995  *  false, if $capability is set and not found,
 996  *  array if $capability not set)
 997  */
 998 function sqimap_capability($imap_stream, $capability='', $bUseCache=true) {
 999     // sqgetGlobalVar('sqimap_capabilities', $sqimap_capabilities, SQ_SESSION);
1000
1001     if (!$bUseCache || ! sqgetGlobalVar('sqimap_capabilities', $sqimap_capabilities, SQ_SESSION)) {
1002         $read = sqimap_run_command($imap_stream, 'CAPABILITY', true, $a, $b);
1003         $c = explode(' ', $read[0]);
1004         for ($i=2; $i < count($c); $i++) {
1005             $cap_list = explode('=', $c[$i]);
1006             if (isset($cap_list[1])) {
1007                 if(isset($sqimap_capabilities[trim($cap_list[0])]) &&
1008                  !is_array($sqimap_capabilities[trim($cap_list[0])])) {
1009                     // Remove array key that was added in 'else' block below
1010                     // This is to accomodate for capabilities like:
1011                     // SORT SORT=MODSEQ
1012                     unset($sqimap_capabilities[trim($cap_list[0])]);
1013                 }
1014                 $sqimap_capabilities[trim($cap_list[0])][] = $cap_list[1];
1015             } else {
1016                 if(!isset($sqimap_capabilities[trim($cap_list[0])])) {
1017                     $sqimap_capabilities[trim($cap_list[0])] = TRUE;
1018                 }
1019             }
1020         }
1021     }
1022     if ($capability) {
1023         if (isset($sqimap_capabilities[$capability])) {
1024                 return $sqimap_capabilities[$capability];
1025         } else {
1026                 return false;
1027         }
1028     }
1029     return $sqimap_capabilities;
1030 }
1031
1032 /**
1033  * Returns the delimiter between mailboxes: INBOX/Test, or INBOX.Test
1034  * @param stream $imap_stream
1035  * @return string
1036  */
1037 function sqimap_get_delimiter ($imap_stream = false) {
1038     global $sqimap_delimiter, $optional_delimiter;
1039
1040     /* Use configured delimiter if set */
1041     if((!empty($optional_delimiter)) && $optional_delimiter != 'detect') {
1042         return $optional_delimiter;
1043     }
1044
1045     /* Delimiter is stored in the session from redirect.  Try fetching from there first */
1046     if (empty($sqimap_delimiter)) {
1047         sqgetGlobalVar('delimiter',$sqimap_delimiter,SQ_SESSION);
1048     }
1049
1050     /* Do some caching here */
1051     if (!$sqimap_delimiter) {
1052         if (sqimap_capability($imap_stream, 'NAMESPACE')) {
1053             /*
1054              * According to something that I can't find, this is supposed to work on all systems
1055              * OS: This won't work in Courier IMAP.
1056              * OS: According to rfc2342 response from NAMESPACE command is:
1057              * OS: * NAMESPACE (PERSONAL NAMESPACES) (OTHER_USERS NAMESPACE) (SHARED NAMESPACES)
1058              * OS: We want to lookup all personal NAMESPACES...
1059              *
1060              * TODO: remove this in favour of the information from sqimap_get_namespace()
1061              */
1062             $read = sqimap_run_command($imap_stream, 'NAMESPACE', true, $a, $b);
1063             if (eregi('\\* NAMESPACE +(\\( *\\(.+\\) *\\)|NIL) +(\\( *\\(.+\\) *\\)|NIL) +(\\( *\\(.+\\) *\\)|NIL)', $read[0], $data)) {
1064                 if (eregi('^\\( *\\((.*)\\) *\\)', $data[1], $data2)) {
1065                     $pn = $data2[1];
1066                 }
1067                 $pna = explode(')(', $pn);
1068                 while (list($k, $v) = each($pna)) {
1069                     $lst = explode('"', $v);
1070                     if (isset($lst[3])) {
1071                         $pn[$lst[1]] = $lst[3];
1072                     } else {
1073                         $pn[$lst[1]] = '';
1074                     }
1075                 }
1076             }
1077             $sqimap_delimiter = $pn[0];
1078         } else {
1079             fputs ($imap_stream, ". LIST \"INBOX\" \"\"\r\n");
1080             $read = sqimap_read_data($imap_stream, '.', true, $a, $b);
1081             $read = $read['.'][0];    //sqimap_read_data() now returns a tag array of response array
1082             $quote_position = strpos ($read[0], '"');
1083             $sqimap_delimiter = substr ($read[0], $quote_position+1, 1);
1084         }
1085     }
1086     return $sqimap_delimiter;
1087 }
1088
1089 /**
1090  * Retrieves the namespaces from the IMAP server.
1091  * NAMESPACE is an IMAP extension defined in RFC 2342.
1092  *
1093  * @param stream $imap_stream
1094  * @return array
1095  */
1096 function sqimap_get_namespace($imap_stream) {
1097     $read = sqimap_run_command($imap_stream, 'NAMESPACE', true, $a, $b);
1098     return sqimap_parse_namespace($read[0]);
1099 }
1100
1101 /**
1102  * Parses a NAMESPACE response and returns an array with the available
1103  * personal, users and shared namespaces.
1104  *
1105  * @param string $input
1106  * @return array The returned array has the following format:
1107  * <pre>
1108  * array(
1109  *   'personal' => array(
1110  *       0 => array('prefix'=>'INBOX.','delimiter' =>'.'),
1111  *       1 => ...
1112  *    ),
1113  *    'users' => array(..
1114  *    ),
1115  *    'shared' => array( ..
1116  *    )
1117  * )
1118  * </pre>
1119  * Note that if a namespace is not defined in the server, then the corresponding
1120  * array will be empty.
1121  */
1122 function sqimap_parse_namespace(&$input) {
1123     $ns_strings = array(1=>'personal', 2=>'users', 3=>'shared');
1124     $namespace = array();
1125
1126     if(ereg('NAMESPACE (\(\(.*\)\)|NIL) (\(\(.*\)\)|NIL) (\(\(.*\)\)|NIL)', $input, $regs) !== false) {
1127         for($i=1; $i<=3; $i++) {
1128             if($regs[$i] == 'NIL') {
1129                 $namespace[$ns_strings[$i]] = array();
1130             } else {
1131                 // Pop-out the first ( and last ) for easier parsing
1132                 $ns = substr($regs[$i], 1, sizeof($regs[$i])-2);
1133                 if($c = preg_match_all('/\((?:(.*?)\s*?)\)/', $ns, $regs2)) {
1134                     $namespace[$ns_strings[$i]] = array();
1135                     for($j=0; $j<sizeof($regs2[1]); $j++) {
1136                         preg_match('/"(.*)"\s+("(.*)"|NIL)/', $regs2[1][$j], $regs3);
1137                         $namespace[$ns_strings[$i]][$j]['prefix'] = $regs3[1];
1138                         if($regs3[2] == 'NIL') {
1139                             $namespace[$ns_strings[$i]][$j]['delimiter'] = null;
1140                         } else {
1141                             // $regs[3] is $regs[2] without the quotes
1142                             $namespace[$ns_strings[$i]][$j]['delimiter'] = $regs3[3];
1143                         }
1144                         unset($regs3);
1145                     }
1146                 }
1147                 unset($ns);
1148             }
1149         }
1150     }
1151     return($namespace);
1152 }
1153
1154 /**
1155  * This encodes a mailbox name for use in IMAP commands.
1156  * @param string $what the mailbox to encode
1157  * @return string the encoded mailbox string
1158  * @since 1.5.0
1159  */
1160 function sqimap_encode_mailbox_name($what)
1161 {
1162     if (ereg("[\"\\\r\n]", $what))
1163         return '{' . strlen($what) . "}\r\n" . $what;        /* 4.3 literal form */
1164     return '"' . $what . '"';        /* 4.3 quoted string form */
1165 }
1166
1167 /**
1168  * Gets the number of messages in the current mailbox.
1169  *
1170  * OBSOLETE use sqimap_status_messages instead.
1171  * @param stream $imap_stream imap stream
1172  * @param string $mailbox
1173  * @deprecated
1174  */
1175 function sqimap_get_num_messages ($imap_stream, $mailbox) {
1176     $aStatus = sqimap_status_messages($imap_stream,$mailbox,array('MESSAGES'));
1177     return $aStatus['MESSAGES'];
1178 }
1179
1180 /**
1181  * OBSOLETE FUNCTION should be removed after mailbox_display,
1182  * printMessage function is adapted
1183  * $addr_ar = array(), $group = '' and $host='' arguments are used in 1.4.0
1184  * @param string $address
1185  * @param integer $max
1186  * @since 1.4.0
1187  * @deprecated See Rfc822Address.php
1188  */
1189 function parseAddress($address, $max=0) {
1190     $aAddress = parseRFC822Address($address,array('limit'=> $max));
1191     /*
1192      * Because the expected format of the array element is changed we adapt it now.
1193      * This also implies that this function is obsolete and should be removed after the
1194      * rest of the source is adapted. See Rfc822Address.php for the new function.
1195      */
1196      array_walk($aAddress, '_adaptAddress');
1197      return $aAddress;
1198 }
1199
1200 /**
1201  * OBSOLETE FUNCTION should be removed after mailbox_display,
1202  * printMessage function is adapted
1203  *
1204  * callback function used for formating of addresses array in
1205  * parseAddress() function
1206  * @param array $aAddr
1207  * @param integer $k array key
1208  * @since 1.5.1
1209  * @deprecated
1210  */
1211 function _adaptAddress(&$aAddr,$k) {
1212    $sPersonal = (isset($aAddr[SQM_ADDR_PERSONAL]) && $aAddr[SQM_ADDR_PERSONAL]) ?
1213        $aAddr[SQM_ADDR_PERSONAL] : '';
1214    $sEmail = ($aAddr[SQM_ADDR_HOST]) ?
1215        $aAddr[SQM_ADDR_MAILBOX] . '@'.$aAddr[SQM_ADDR_HOST] :
1216        $aAddr[SQM_ADDR_MAILBOX];
1217    $aAddr = array($sEmail,$sPersonal);
1218 }
1219
1220 /**
1221  * Returns the number of unseen messages in this folder.
1222  * obsoleted by sqimap_status_messages !
1223  * Arguments differ in 1.0.x
1224  * @param stream $imap_stream
1225  * @param string $mailbox
1226  * @return integer
1227  * @deprecated
1228  */
1229 function sqimap_unseen_messages ($imap_stream, $mailbox) {
1230     $aStatus = sqimap_status_messages($imap_stream,$mailbox,array('UNSEEN'));
1231     return $aStatus['UNSEEN'];
1232 }
1233
1234 /**
1235  * Returns the status items of a mailbox.
1236  * Default it returns MESSAGES,UNSEEN and RECENT
1237  * Supported status items are MESSAGES, UNSEEN, RECENT (since 1.4.0),
1238  * UIDNEXT (since 1.5.1) and UIDVALIDITY (since 1.5.1)
1239  * @param stream $imap_stream imap stream
1240  * @param string $mailbox mail folder
1241  * @param array $aStatusItems status items
1242  * @return array
1243  * @since 1.3.2
1244  */
1245 function sqimap_status_messages ($imap_stream, $mailbox,
1246                        $aStatusItems = array('MESSAGES','UNSEEN','RECENT')) {
1247
1248     $aStatusItems = implode(' ',$aStatusItems);
1249     $read_ary = sqimap_run_command ($imap_stream, 'STATUS ' . sqimap_encode_mailbox_name($mailbox) .
1250                                     " ($aStatusItems)", false, $result, $message);
1251     $i = 0;
1252     $messages = $unseen = $recent = $uidnext = $uidvalidity = false;
1253     $regs = array(false,false);
1254     while (isset($read_ary[$i])) {
1255         if (preg_match('/UNSEEN\s+([0-9]+)/i', $read_ary[$i], $regs)) {
1256             $unseen = $regs[1];
1257         }
1258         if (preg_match('/MESSAGES\s+([0-9]+)/i', $read_ary[$i], $regs)) {
1259             $messages = $regs[1];
1260         }
1261         if (preg_match('/RECENT\s+([0-9]+)/i', $read_ary[$i], $regs)) {
1262             $recent = $regs[1];
1263         }
1264         if (preg_match('/UIDNEXT\s+([0-9]+)/i', $read_ary[$i], $regs)) {
1265             $uidnext = $regs[1];
1266         }
1267         if (preg_match('/UIDVALIDITY\s+([0-9]+)/i', $read_ary[$i], $regs)) {
1268             $uidvalidity = $regs[1];
1269         }
1270         $i++;
1271     }
1272
1273     $status=array('MESSAGES' => $messages,
1274                  'UNSEEN'=>$unseen,
1275                  'RECENT' => $recent,
1276                  'UIDNEXT' => $uidnext,
1277                  'UIDVALIDITY' => $uidvalidity);
1278
1279     if (!empty($messages)) { $hook_status['MESSAGES']=$messages; }
1280     if (!empty($unseen)) { $hook_status['UNSEEN']=$unseen; }
1281     if (!empty($recent)) { $hook_status['RECENT']=$recent; }
1282     if (!empty($hook_status)) {
1283          $hook_status['MAILBOX']=$mailbox;
1284          $hook_status['CALLER']='sqimap_status_messages';
1285          do_hook('folder_status', $hook_status);
1286     }
1287     return $status;
1288 }
1289
1290
1291 /**
1292  * Saves a message to a given folder -- used for saving sent messages
1293  * @param stream $imap_stream
1294  * @param string $sent_folder
1295  * @param $length
1296  * @return string $sid
1297  */
1298 function sqimap_append ($imap_stream, $sMailbox, $length) {
1299     $sid = sqimap_session_id();
1300     $query = $sid . ' APPEND ' . sqimap_encode_mailbox_name($sMailbox) . " (\\Seen) {".$length."}";
1301     fputs ($imap_stream, "$query\r\n");
1302     $tmp = fgets ($imap_stream, 1024);
1303     sqimap_append_checkresponse($tmp, $sMailbox,$sid, $query);
1304     return $sid;
1305 }
1306
1307 /**
1308  * @param stream imap_stream
1309  * @param string $folder (since 1.3.2)
1310  */
1311 function sqimap_append_done ($imap_stream, $sMailbox='') {
1312     fputs ($imap_stream, "\r\n");
1313     $tmp = fgets ($imap_stream, 1024);
1314     while (!sqimap_append_checkresponse($tmp, $sMailbox)) {
1315         $tmp = fgets ($imap_stream, 1024);
1316     }
1317 }
1318
1319 /**
1320  * Displays error messages, if there are errors in responses to
1321  * commands issues by sqimap_append() and sqimap_append_done() functions.
1322  * @param string $response
1323  * @param string $sMailbox
1324  * @return bool $bDone
1325  * @since 1.5.1 and 1.4.5
1326  */
1327 function sqimap_append_checkresponse($response, $sMailbox, $sid='', $query='') {
1328     // static vars to keep them available when sqimap_append_done calls this function.
1329     static $imapquery, $imapsid;
1330
1331     $bDone = false;
1332
1333     if ($query) {
1334         $imapquery = $query;
1335     }
1336     if ($sid) {
1337         $imapsid = $sid;
1338     }
1339     if ($response{0} == '+') {
1340         // continuation request triggerd by sqimap_append()
1341         $bDone = true;
1342     } else {
1343         $i = strpos($response, ' ');
1344         $sRsp = substr($response,0,$i);
1345         $sMsg = substr($response,$i+1);
1346         $aExtra = array('MAILBOX' => $sMailbox);
1347         switch ($sRsp) {
1348             case '*': //untagged response
1349                 $i = strpos($sMsg, ' ');
1350                 $sRsp = strtoupper(substr($sMsg,0,$i));
1351                 $sMsg = substr($sMsg,$i+1);
1352                 if ($sRsp == 'NO' || $sRsp == 'BAD') {
1353                     // for the moment disabled. Enable after 1.5.1 release.
1354                     // Notices could give valueable information about the mailbox
1355                     // sqm_trigger_imap_error('SQM_IMAP_APPEND_NOTICE',$imapquery,$sRsp,$sMsg);
1356                 }
1357                 $bDone = false;
1358             case $imapsid:
1359                 // A001 OK message
1360                 // $imapsid<space>$sRsp<space>$sMsg
1361                 $bDone = true;
1362                 $i = strpos($sMsg, ' ');
1363                 $sRsp = strtoupper(substr($sMsg,0,$i));
1364                 $sMsg = substr($sMsg,$i+1);
1365                 switch ($sRsp) {
1366                     case 'NO':
1367                         if (preg_match("/(.*)(quota)(.*)$/i", $sMsg, $aMatch)) {
1368                             sqm_trigger_imap_error('SQM_IMAP_APPEND_QUOTA_ERROR',$imapquery,$sRsp,$sMsg,$aExtra);
1369                         } else {
1370                             sqm_trigger_imap_error('SQM_IMAP_APPEND_ERROR',$imapquery,$sRsp,$sMsg,$aExtra);
1371                         }
1372                         break;
1373                     case 'BAD':
1374                         sqm_trigger_imap_error('SQM_IMAP_ERROR',$imapquery,$sRsp,$sMsg,$aExtra);
1375                         break;
1376                     case 'BYE':
1377                         sqm_trigger_imap_error('SQM_IMAP_BYE',$imapquery,$sRsp,$sMsg,$aExtra);
1378                         break;
1379                     case 'OK':
1380                         break;
1381                     default:
1382                         break;
1383                 }
1384                 break;
1385             default:
1386                 // should be false because of the unexpected response but i'm not sure if
1387                 // that will cause an endless loop in sqimap_append_done
1388                 $bDone = true;
1389         }
1390     }
1391     return $bDone;
1392 }
1393
1394 /**
1395  * Allows mapping of IMAP server address with custom function
1396  * see map_yp_alias()
1397  * @param string $imap_server imap server address or mapping
1398  * @param string $username
1399  * @return string
1400  * @since 1.3.0
1401  */
1402 function sqimap_get_user_server ($imap_server, $username) {
1403    if (substr($imap_server, 0, 4) != "map:") {
1404        return $imap_server;
1405    }
1406    $function = substr($imap_server, 4);
1407    return $function($username);
1408 }
1409
1410 /**
1411  * This is an example that gets IMAP servers from yellowpages (NIS).
1412  * you can simple put map:map_yp_alias in your $imap_server_address
1413  * in config.php use your own function instead map_yp_alias to map your
1414  * LDAP whatever way to find the users IMAP server.
1415  *
1416  * Requires access to external ypmatch program
1417  * FIXME: it can be implemented in php yp extension or pecl (since php 5.1.0)
1418  * @param string $username
1419  * @return string
1420  * @since 1.3.0
1421  */
1422 function map_yp_alias($username) {
1423    $yp = `ypmatch $username aliases`;
1424    return chop(substr($yp, strlen($username)+1));
1425 }