X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=functions%2Fimap_general.php;h=eca66b886dfefb96cd14958dfa3d92ade57ac1d6;hb=887f7f28f8e85139eae7031a63d8c88c4832dfca;hp=319dcac85bc29a5f089a177f5fb07a21fc263726;hpb=1d20443c04896d47c55cdba84b337558e592a9d2;p=squirrelmail.git diff --git a/functions/imap_general.php b/functions/imap_general.php index 319dcac8..eca66b88 100755 --- a/functions/imap_general.php +++ b/functions/imap_general.php @@ -6,7 +6,7 @@ * 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. + * This implements all functions that do general IMAP functions. * * @version $Id$ * @package squirrelmail @@ -21,7 +21,7 @@ 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 (since 1.3.0) controls use of unique + * @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'. @@ -40,15 +40,13 @@ 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 stream $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 + * @param array $response + * @param array $message + * @param boolean $unique_id (since 1.3.0) see sqimap_session_id(). + * @return mixed returns false on imap error. displays error message * if imap stream is not available. * @since 1.2.3 */ @@ -68,7 +66,7 @@ function sqimap_run_command_list ($imap_stream, $query, $handle_errors, &$respon set_up_language($squirrelmail_language); require_once(SM_PATH . 'functions/display_messages.php'); $string = "\n" . - _("ERROR : No available imapstream.") . + _("ERROR: No available IMAP stream.") . "\n"; error_box($string,$color); return false; @@ -76,18 +74,16 @@ function sqimap_run_command_list ($imap_stream, $query, $handle_errors, &$respon } /** - * @param resource $imap_stream imap connection resource + * @param stream $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 + * @param array $response empty string, if return = false + * @param array $message empty string, if return = false + * @param boolean $unique_id (since 1.3.0) see sqimap_session_id() + * @param boolean $filter (since 1.4.1 and 1.5.0) see sqimap_fread() + * @param mixed $outputstream (since 1.4.1 and 1.5.0) see sqimap_fread() + * @param boolean $no_return (since 1.4.1 and 1.5.0) see sqimap_fread() + * @return mixed returns false on imap error. displays error message * if imap stream is not available. * @since 1.2.3 */ @@ -102,7 +98,7 @@ function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response, $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; @@ -121,7 +117,7 @@ function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response, set_up_language($squirrelmail_language); require_once(SM_PATH . 'functions/display_messages.php'); $string = "\n" . - _("ERROR : No available imapstream.") . + _("ERROR: No available IMAP stream.") . "\n"; error_box($string,$color); return false; @@ -132,7 +128,7 @@ function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response, * @param mixed $new_query * @param string $tag * @param array $aQuery - * @param boolean $unique_id + * @param boolean $unique_id see sqimap_session_id() * @since 1.5.0 */ function sqimap_prepare_pipelined_query($new_query,&$tag,&$aQuery,$unique_id) { @@ -144,15 +140,15 @@ function sqimap_prepare_pipelined_query($new_query,&$tag,&$aQuery,$unique_id) { } /** - * @param stream $imap_stream + * @param stream $imap_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() + * @param boolean $unique_id see sqimap_session_id() + * @param boolean $filter see sqimap_fread() + * @param mixed $outputstream see sqimap_fread() + * @param boolean $no_return see sqimap_fread() * @since 1.5.0 */ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors, @@ -161,9 +157,9 @@ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors $aResponse = false; /* - Do not fire all calls at once to the imap-server but split the calls up + 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 - IMAP client or should handle BYE calls if the IMAP-server drops the + 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. @@ -219,9 +215,9 @@ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors } /** - * Custom fgets function: gets a line from the IMAP-server, + * 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 + * @param stream $imap_stream the stream to read from * @return string a line * @since 1.2.8 */ @@ -248,9 +244,9 @@ function sqimap_fgets($imap_stream) { /** * @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() + * @param boolean $filter + * @param mixed $outputstream stream or 'php://stdout' string + * @param boolean $no_return controls data returned by function * @return string * @since 1.4.1 */ @@ -310,6 +306,12 @@ function sqimap_fread($imap_stream,$iSize,$filter=false, /** * Obsolete function, inform plugins that use it + * @param stream $imap_stream + * @param string $tag + * @param boolean $handle_errors + * @param array $response + * @param array $message + * @param string $query * @since 1.1.3 * @deprecated (since 1.5.0) use sqimap_run_command or sqimap_run_command_list instead */ @@ -319,7 +321,7 @@ function sqimap_read_data_list($imap_stream, $tag, $handle_errors, set_up_language($squirrelmail_language); require_once(SM_PATH . 'functions/display_messages.php'); $string = "\n" . - _("ERROR : Bad function call.") . + _("ERROR: Bad function call.") . "
\n" . _("Reason:") . ' '. 'There is a plugin installed which make use of the
' . @@ -334,7 +336,7 @@ function sqimap_read_data_list($imap_stream, $tag, $handle_errors, } /** - * Function to display an error related to an IMAP-query. + * Function to display an error related to an IMAP query. * @param string title the caption of the error box * @param string query the query that went wrong * @param string message_title optional message title @@ -369,15 +371,15 @@ 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 stream $imap_stream imap stream + * @param string $tag + * @param boolean $handle_errors handle errors internally or send them in $response and $message. * @param array $response * @param array $message - * @param mixed $query - * @param mixed $filter - * @param mixed $outputstream - * @param mixed $no_return + * @param string $query command that can be printed if something fails + * @param boolean $filter see sqimap_fread() + * @param mixed $outputstream see sqimap_fread() + * @param boolean $no_return see sqimap_fread() * @since 1.5.0 */ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, @@ -547,12 +549,12 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, if (!$handle_errors) { $query = ''; } - sqimap_error_box(_("ERROR : Imap server closed the connection."), $query, _("Server responded:"),$sResponse); + sqimap_error_box(_("ERROR: IMAP server closed the connection."), $query, _("Server responded:"),$sResponse); echo ''; exit; } else if ($handle_errors) { unset($data); - sqimap_error_box(_("ERROR : Connection dropped by imap-server."), $query); + sqimap_error_box(_("ERROR: Connection dropped by IMAP server."), $query); exit; } } @@ -576,21 +578,21 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, 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]); + sqimap_error_box(_("ERROR: Could not complete request."), $query, _("Reason Given:") . ' ', $message[$tag]); echo ''; exit; } break; case 'BAD': - sqimap_error_box(_("ERROR : Bad or malformed request."), $query, _("Server responded: "), $message[$tag]); + sqimap_error_box(_("ERROR: Bad or malformed request."), $query, _("Server responded:") . ' ', $message[$tag]); echo ''; exit; case 'BYE': - sqimap_error_box(_("ERROR : Imap server closed the connection."), $query, _("Server responded: "), $message[$tag]); + sqimap_error_box(_("ERROR: IMAP server closed the connection."), $query, _("Server responded:") . ' ', $message[$tag]); echo ''; exit; default: - sqimap_error_box(_("ERROR : Unknown imap response."), $query, _("Server responded: "), $message[$tag]); + 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; @@ -599,15 +601,15 @@ function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, } /** - * @param stream $imap_stream + * @param stream $imap_stream imap string * @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() + * @param string $query (since 1.2.5) + * @param boolean $filter (since 1.4.1) see sqimap_fread() + * @param mixed $outputstream (since 1.4.1) see sqimap_fread() + * @param boolean $no_return (since 1.4.1) see sqimap_fread() */ function sqimap_read_data ($imap_stream, $tag_uid, $handle_errors, &$response, &$message, $query = '', @@ -643,7 +645,8 @@ function sqimap_create_stream($server,$port,$tls=false) { '
'. _("TLS is enabled, but this version of PHP does not support TLS sockets, or is missing the openssl extension."). '

'. - _("Please contact your system administrator and report this error.") ); + _("Please contact your system administrator and report this error."), + sprintf(_("Error connecting to IMAP server: %s."), $server)); } } @@ -654,7 +657,8 @@ function sqimap_create_stream($server,$port,$tls=false) { set_up_language($squirrelmail_language, true); require_once(SM_PATH . 'functions/display_messages.php'); logout_error( sprintf(_("Error connecting to IMAP server: %s."), $server). - "
\r\n$error_number : $error_string
\r\n" ); + "
\r\n$error_number : $error_string
\r\n", + sprintf(_("Error connecting to IMAP server: %s."), $server) ); exit; } $server_info = fgets ($imap_stream, 1024); @@ -662,8 +666,8 @@ 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. + * 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 @@ -821,26 +825,25 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $ /* Special error case: * Login referrals. The server returns: - * ? OK [REFERRAL ] - * 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); + * ? OK [REFERRAL ] + * Check RFC 2221 for details. Since we do not support login referrals yet + * we log the user out. + */ + if ( stristr($message, 'REFERRAL imap') === TRUE ) { + 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.
". - "Try a different server or consult your Administrator") ); + logout_error( _("Your mailbox is not located at this server. Try a different server or consult your system administrator") ); exit; } - + return $imap_stream; } /** * Simply logs out the IMAP session - * @param stream imap_stream the IMAP connection to log out. + * @param stream $imap_stream the IMAP connection to log out. * @return void */ function sqimap_logout ($imap_stream) { @@ -851,12 +854,12 @@ function sqimap_logout ($imap_stream) { } /** - * Retreive the CAPABILITY string from the IMAP server. + * Retrieve 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 stream $imap_stream * @param string $capability (optional since 1.3.0) - * @return mixed (string if $capability is set and found, + * @return mixed (string if $capability is set and found, * false, if $capability is set and not found, * array if $capability not set) */ @@ -888,7 +891,7 @@ function sqimap_capability($imap_stream, $capability='') { } /** - * Returns the delimeter between mailboxes: INBOX/Test, or INBOX.Test + * Returns the delimiter between mailboxes: INBOX/Test, or INBOX.Test * @param stream $imap_stream * @return string */ @@ -939,7 +942,7 @@ function sqimap_get_delimiter ($imap_stream = false) { /** * This encodes a mailbox name for use in IMAP commands. - * @param string what the mailbox to encode + * @param string $what the mailbox to encode * @return string the encoded mailbox string * @since 1.5.0 */ @@ -954,6 +957,9 @@ function sqimap_encode_mailbox_name($what) * Gets the number of messages in the current mailbox. * * OBSOLETE use sqimap_status_messages instead. + * @param stream $imap_stream imap stream + * @param string $mailbox + * @deprecated */ function sqimap_get_num_messages ($imap_stream, $mailbox) { $read_ary = sqimap_run_command ($imap_stream, 'EXAMINE ' . sqimap_encode_mailbox_name($mailbox), false, $result, $message); @@ -964,11 +970,18 @@ function sqimap_get_num_messages ($imap_stream, $mailbox) { } return false; //"BUG! Couldn't get number of messages in $mailbox!"; } + +/** FIXME: include is inserted in the middle of the code */ include_once(SM_PATH . 'functions/rfc822address.php'); /** * OBSOLETE FUNCTION should be removed after mailbox_display, * printMessage function is adapted + * $addr_ar = array(), $group = '' and $host='' arguments are used in 1.4.0 + * @param string $address + * @param integer $max + * @since 1.4.0 + * @deprecated See Rfc822Address.php */ function parseAddress($address, $max=0) { $aAddress = parseRFC822Address($address,array('limit'=> $max)); @@ -984,6 +997,13 @@ function parseAddress($address, $max=0) { /** * OBSOLETE FUNCTION should be removed after mailbox_display, * printMessage function is adapted + * + * callback function used for formating of addresses array in + * parseAddress() function + * @param array $aAddr + * @param integer $k array key + * @since 1.5.1 + * @deprecated */ function _adaptAddress(&$aAddr,$k) { $sPersonal = (isset($aAddr[SQM_ADDR_PERSONAL]) && $aAddr[SQM_ADDR_PERSONAL]) ? @@ -997,6 +1017,11 @@ function _adaptAddress(&$aAddr,$k) { /** * Returns the number of unseen messages in this folder. * obsoleted by sqimap_status_messages ! + * Arguments differ in 1.0.x + * @param stream $imap_stream + * @param string $mailbox + * @return integer + * @deprecated */ function sqimap_unseen_messages ($imap_stream, $mailbox) { $aStatus = sqimap_status_messages($imap_stream,$mailbox,array('UNSEEN')); @@ -1006,7 +1031,13 @@ function sqimap_unseen_messages ($imap_stream, $mailbox) { /** * Returns the status items of a mailbox. * Default it returns MESSAGES,UNSEEN and RECENT - * Supported status items are MESSAGES, UNSEEN, RECENT, UIDNEXT and UIDVALIDITY + * Supported status items are MESSAGES, UNSEEN, RECENT (since 1.4.0), + * UIDNEXT (since 1.5.1) and UIDVALIDITY (since 1.5.1) + * @param stream $imap_stream imap stream + * @param string $mailbox mail folder + * @param array $aStatusItems status items + * @return array + * @since 1.3.2 */ function sqimap_status_messages ($imap_stream, $mailbox, $aStatusItems = array('MESSAGES','UNSEEN','RECENT')) { @@ -1045,6 +1076,9 @@ function sqimap_status_messages ($imap_stream, $mailbox, /** * Saves a message to a given folder -- used for saving sent messages + * @param stream $imap_stream + * @param string $sent_folder + * @param $length */ 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"); @@ -1052,14 +1086,25 @@ function sqimap_append ($imap_stream, $sent_folder, $length) { sqimap_append_checkresponse($tmp, $sent_folder); } +/** + * @param stream imap_stream + * @param string $folder (since 1.3.2) + */ function sqimap_append_done ($imap_stream, $folder='') { fputs ($imap_stream, "\r\n"); $tmp = fgets ($imap_stream, 1024); sqimap_append_checkresponse($tmp, $folder); } +/** + * Displays error messages, if there are errors in responses to + * commands issues by sqimap_append() and sqimap_append_done() functions. + * @param string $response + * @param string $folder + * @since 1.5.1 + */ function sqimap_append_checkresponse($response, $folder) { - + if (preg_match("/(.*)(BAD|NO)(.*)$/", $response, $regs)) { global $squirrelmail_language, $color; set_up_language($squirrelmail_language); @@ -1068,12 +1113,12 @@ function sqimap_append_checkresponse($response, $folder) { $reason = $regs[3]; if ($regs[2] == 'NO') { $string = "\n" . - _("ERROR : Could not append message to") ." $folder." . + _("ERROR: Could not append message to") ." $folder." . "
\n" . - _("Server responded: ") . + _("Server responded:") . ' ' . $reason . "
\n"; if (preg_match("/(.*)(quota)(.*)$/i", $reason, $regs)) { - $string .= _("Solution: ") . + $string .= _("Solution:") . ' ' . _("Remove unneccessary messages from your folder and start with your Trash folder.") ."
\n"; } @@ -1081,9 +1126,9 @@ function sqimap_append_checkresponse($response, $folder) { error_box($string,$color); } else { $string = "\n" . - _("ERROR : Bad or malformed request.") . + _("ERROR: Bad or malformed request.") . "
\n" . - _("Server responded: ") . + _("Server responded:") . ' ' . $reason . "
\n"; error_box($string,$color); exit; @@ -1091,6 +1136,14 @@ function sqimap_append_checkresponse($response, $folder) { } } +/** + * Allows mapping of IMAP server address with custom function + * see map_yp_alias() + * @param string $imap_server imap server address or mapping + * @param string $username + * @return string + * @since 1.3.0 + */ function sqimap_get_user_server ($imap_server, $username) { if (substr($imap_server, 0, 4) != "map:") { return $imap_server; @@ -1100,10 +1153,16 @@ function sqimap_get_user_server ($imap_server, $username) { } /** - * This is an example that gets imapservers from yellowpages (NIS). + * This is an example that gets IMAP servers from yellowpages (NIS). * 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. + * LDAP whatever way to find the users IMAP server. + * + * Requires access to external ypmatch program + * FIXME: it can be implemented in php yp extension or pecl (since php 5.1.0) + * @param string $username + * @return string + * @since 1.3.0 */ function map_yp_alias($username) { $yp = `ypmatch $username aliases`;