documenting two functions

[squirrelmail.git] / functions / imap_messages.php

diff --git a/functions/imap_messages.php b/functions/imap_messages.php
index 7f4614872f8ba91b1f77810e6df169ec4dae7fca..92b96a9f115e447a7c920e755810150407638dfd 100755 (executable)
--- a/functions/imap_messages.php
+++ b/functions/imap_messages.php
@@ -20,11 +20,12 @@
  * @param int $imap_stream The resource ID for the IMAP socket
  * @param string $id The list of messages to copy
  * @param string $mailbox The destination to copy to
- * @return bool
+ * @param bool $handle_errors Show error messages in case of a NO, BAD or BYE response
+ * @return bool If the copy completed without errors  
  */
-function sqimap_msgs_list_copy($imap_stream, $id, $mailbox) {
+function sqimap_msgs_list_copy($imap_stream, $id, $mailbox, $handle_errors = true) {
     $msgs_id = sqimap_message_list_squisher($id);
-    $read = sqimap_run_command ($imap_stream, "COPY $msgs_id " . sqimap_encode_mailbox_name($mailbox), true, $response, $message, TRUE);
+    $read = sqimap_run_command ($imap_stream, "COPY $msgs_id " . sqimap_encode_mailbox_name($mailbox), $handle_errors, $response, $message, TRUE);
     if ($response == 'OK') {
         return true;
     } else {
@@ -38,11 +39,12 @@ function sqimap_msgs_list_copy($imap_stream, $id, $mailbox) {
  * @param int $imap_stream The resource ID for the IMAP socket
  * @param string $id The list of messages to move
  * @param string $mailbox The destination to move to
- * @return void
+ * @param bool $handle_errors Show error messages in case of a NO, BAD or BYE response
+ * @return bool If the move completed without errors
  */
-function sqimap_msgs_list_move($imap_stream, $id, $mailbox) {
+function sqimap_msgs_list_move($imap_stream, $id, $mailbox, $handle_errors = true) {
     $msgs_id = sqimap_message_list_squisher($id);
-    if (sqimap_msgs_list_copy ($imap_stream, $id, $mailbox)) {
+    if (sqimap_msgs_list_copy ($imap_stream, $id, $mailbox, $handle_errors)) {
         return sqimap_toggle_flag($imap_stream, $id, '\\Deleted', true, true);
     } else {
         return false;
@@ -55,8 +57,9 @@ function sqimap_msgs_list_move($imap_stream, $id, $mailbox) {
  * @param  resource imap connection
  * @param  string $mailbox mailbox, used for checking if it concerns the trash_folder
  * @param  array $id list with uid's
- * @param  bool   $bypass_trash skip copy to trash
+ * @param  bool   $bypass_trash (since 1.5.0) skip copy to trash
  * @return array  $aMessageList array with messages containing the new flags and UID @see parseFetch
+ * @since 1.4.0
  */
 function sqimap_msgs_list_delete($imap_stream, $mailbox, $id, $bypass_trash=false) {
     // FIX ME, remove globals by introducing an associative array with properties
@@ -577,11 +580,15 @@ function parseArray($read,&$i) {
 
 /**
  * Retrieves a list with headers, flags, size or internaldate from the imap server
- * @param resource $imap_stream imap connection
- * @param array    $msg_list array with id's to create a msgs set from
- * @param array    $aHeaderFields requested header fields
- * @param array    $aFetchItems   requested other fetch items like FLAGS, RFC822.SIZE
- * @return array   $aMessages associative array with messages. Key is the UID, value is an associative array
+ *
+ * WARNING: function is not portable between SquirrelMail 1.2.x, 1.4.x and 1.5.x. 
+ * Output format, third argument and $msg_list array format requirements differ.
+ * @param stream $imap_stream imap connection
+ * @param array  $msg_list array with id's to create a msgs set from
+ * @param array  $aHeaderFields (since 1.5.0) requested header fields
+ * @param array  $aFetchItems (since 1.5.0) requested other fetch items like FLAGS, RFC822.SIZE
+ * @return array $aMessages (since 1.5.0) associative array with messages. Key is the UID, value is an associative array
+ * @since 1.1.3
  */
 function sqimap_get_small_header_list($imap_stream, $msg_list,
     $aHeaderFields = array('Date', 'To', 'Cc', 'From', 'Subject', 'X-Priority', 'Importance', 'Priority', 'Content-Type'),