adding index files in order to prevent directory listing.
[squirrelmail.git] / class / mime / Rfc822Header.class.php
index 5114144..7507349 100644 (file)
@@ -6,15 +6,23 @@
  * Copyright (c) 2003-2005 The SquirrelMail Project Team
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
  * Copyright (c) 2003-2005 The SquirrelMail Project Team
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
- * This contains functions needed to handle mime messages.
+ * This file contains functions needed to handle headers in mime messages.
  *
  * @version $Id$
  * @package squirrelmail
  *
  * @version $Id$
  * @package squirrelmail
+ * @subpackage mime
+ * @since 1.3.2
  */
 
 /**
  */
 
 /**
+ * MIME header class
  * input: header_string or array
  * input: header_string or array
+ * You must call parseHeader() function after creating object in order to fill object's
+ * parameters.
+ * @todo FIXME: there is no constructor function and class should ignore all input args.
  * @package squirrelmail
  * @package squirrelmail
+ * @subpackage mime
+ * @since 1.3.0
  */
 class Rfc822Header {
     var $date = -1,
  */
 class Rfc822Header {
     var $date = -1,
@@ -41,11 +49,15 @@ class Rfc822Header {
         $mlist = array(),
         $more_headers = array(); /* only needed for constructing headers
                                     in smtp.php */
         $mlist = array(),
         $more_headers = array(); /* only needed for constructing headers
                                     in smtp.php */
+    /**
+     * @param mixed $hdr string or array with message headers
+     */
     function parseHeader($hdr) {
         if (is_array($hdr)) {
             $hdr = implode('', $hdr);
         }
         /* First we replace \r\n by \n and unfold the header */
     function parseHeader($hdr) {
         if (is_array($hdr)) {
             $hdr = implode('', $hdr);
         }
         /* First we replace \r\n by \n and unfold the header */
+        /* FIXME: unfolding header with multiple spaces "\n( +)" */
         $hdr = trim(str_replace(array("\r\n", "\n\t", "\n "),array("\n", ' ', ' '), $hdr));
 
         /* Now we can make a new header array with */
         $hdr = trim(str_replace(array("\r\n", "\n\t", "\n "),array("\n", ' ', ' '), $hdr));
 
         /* Now we can make a new header array with */
@@ -66,6 +78,10 @@ class Rfc822Header {
         }
     }
 
         }
     }
 
+    /**
+     * @param string $value
+     * @return string
+     */
     function stripComments($value) {
         $result = '';
         $cnt = strlen($value);
     function stripComments($value) {
         $result = '';
         $cnt = strlen($value);
@@ -108,6 +124,11 @@ class Rfc822Header {
         return $result;
     }
 
         return $result;
     }
 
+    /**
+     * Parse header field according to field type
+     * @param string $field field name
+     * @param string $value field value
+     */
     function parseField($field, $value) {
         $field = strtolower($field);
         switch($field) {
     function parseField($field, $value) {
         $field = strtolower($field);
         switch($field) {
@@ -227,6 +248,10 @@ class Rfc822Header {
         }
     }
 
         }
     }
 
+    /**
+     * @param string $address
+     * @return array
+     */
     function getAddressTokens($address) {
         $aTokens = array();
         $aSpecials = array('(' ,'<' ,',' ,';' ,':');
     function getAddressTokens($address) {
         $aTokens = array();
         $aSpecials = array('(' ,'<' ,',' ,';' ,':');
@@ -351,6 +376,14 @@ class Rfc822Header {
         }
         return $aTokens;
     }
         }
         return $aTokens;
     }
+
+    /**
+     * @param array $aStack
+     * @param array $aComment
+     * @param string $sEmail
+     * @param string $sGroup
+     * @return object AddressStructure object
+     */
     function createAddressObject(&$aStack,&$aComment,&$sEmail,$sGroup='') {
         //$aStack=explode(' ',implode('',$aStack));
         if (!$sEmail) {
     function createAddressObject(&$aStack,&$aComment,&$sEmail,$sGroup='') {
         //$aStack=explode(' ',implode('',$aStack));
         if (!$sEmail) {
@@ -387,21 +420,8 @@ class Rfc822Header {
         return $oAddr;
     }
 
         return $oAddr;
     }
 
-    /*
-     * parseAddress: recursive function for parsing address strings and store
-     *               them in an address stucture object.
-     *               input: $address = string
-     *                      $ar      = boolean (return array instead of only the
-     *                                 first element)
-     *                      $addr_ar = array with parsed addresses // obsolete
-     *                      $group   = string // obsolete
-     *                      $host    = string (default domainname in case of
-     *                                 addresses without a domainname)
-     *                      $lookup  = callback function (for lookup address
-     *                                 strings which are probably nicks
-     *                                 (without @ ) )
-     *               output: array with addressstructure objects or only one
-     *                       address_structure object.
+    /**
+     * recursive function for parsing address strings and storing them in an address stucture object.
      *  personal name: encoded: =?charset?Q|B?string?=
      *                 quoted:  "string"
      *                 normal:  string
      *  personal name: encoded: =?charset?Q|B?string?=
      *                 quoted:  "string"
      *                 normal:  string
@@ -409,8 +429,14 @@ class Rfc822Header {
      *               : mailbox@host
      *  This function is also used for validating addresses returned from compose
      *  That's also the reason that the function became a little bit huge
      *               : mailbox@host
      *  This function is also used for validating addresses returned from compose
      *  That's also the reason that the function became a little bit huge
+     * @param string $address
+     * @param boolean $ar return array instead of only the first element
+     * @param array $addr_ar (obsolete) array with parsed addresses
+     * @param string $group (obsolete)
+     * @param string $host default domainname in case of addresses without a domainname
+     * @param string $lookup (since) callback function for lookup of address strings which are probably nicks (without @)
+     * @return mixed array with AddressStructure objects or only one address_structure object.
      */
      */
-
     function parseAddress($address,$ar=false,$aAddress=array(),$sGroup='',$sHost='',$lookup=false) {
         $aTokens = $this->getAddressTokens($address);
         $sPersonal = $sEmail = $sGroup = '';
     function parseAddress($address,$ar=false,$aAddress=array(),$sGroup='',$sHost='',$lookup=false) {
         $aTokens = $this->getAddressTokens($address);
         $sPersonal = $sEmail = $sGroup = '';
@@ -509,13 +535,15 @@ class Rfc822Header {
     /**
      * Normalise the different Priority headers into a uniform value,
      * namely that of the X-Priority header (1, 3, 5). Supports:
     /**
      * Normalise the different Priority headers into a uniform value,
      * namely that of the X-Priority header (1, 3, 5). Supports:
-     * Prioirty, X-Priority, Importance.
+     * Priority, X-Priority, Importance.
      * X-MS-Mail-Priority is not parsed because it always coincides
      * with one of the other headers.
      *
      * NOTE: this is actually a duplicate from the function in
      * functions/imap_messages. I'm not sure if it's ok here to call
      * that function?
      * X-MS-Mail-Priority is not parsed because it always coincides
      * with one of the other headers.
      *
      * NOTE: this is actually a duplicate from the function in
      * functions/imap_messages. I'm not sure if it's ok here to call
      * that function?
+     * @param string $value literal priority name
+     * @return integer
      */
     function parsePriority($value) {
         $value = strtolower(array_shift(split('/\w/',trim($value))));
      */
     function parsePriority($value) {
         $value = strtolower(array_shift(split('/\w/',trim($value))));
@@ -531,6 +559,9 @@ class Rfc822Header {
         return 3;
     }
 
         return 3;
     }
 
+    /**
+     * @param string $value content type header
+     */
     function parseContentType($value) {
         $pos = strpos($value, ';');
         $props = '';
     function parseContentType($value) {
         $pos = strpos($value, ';');
         $props = '';
@@ -551,7 +582,11 @@ class Rfc822Header {
         $this->content_type = $content_type;
     }
 
         $this->content_type = $content_type;
     }
 
-    /* RFC2184 */
+    /**
+     * RFC2184
+     * @param array $aParameters
+     * @return array
+     */
     function processParameters($aParameters) {
         $aResults = array();
         $aCharset = array();
     function processParameters($aParameters) {
         $aResults = array();
         $aCharset = array();
@@ -578,13 +613,21 @@ class Rfc822Header {
             $value = substr($value,strlen($charset)+1);
             $language = substr($value,0,strpos($value,"'"));
             $value = substr($value,strlen($charset)+1);
             $value = substr($value,strlen($charset)+1);
             $language = substr($value,0,strpos($value,"'"));
             $value = substr($value,strlen($charset)+1);
-            // FIX ME What's the status of charset decode with language information ????
+            /* FIXME: What's the status of charset decode with language information ????
+             * Maybe language information contains only ascii text and charset_decode() 
+             * only runs htmlspecialchars() on it. If it contains 8bit information, you 
+             * get html encoded text in charset used by selected translation.
+             */
             $value = charset_decode($charset,$value);
             $aResults[$key] = $value;
         }
         return $aResults;
     }
 
             $value = charset_decode($charset,$value);
             $aResults[$key] = $value;
         }
         return $aResults;
     }
 
+    /**
+     * @param string $value
+     * @return array
+     */
     function parseProperties($value) {
         $propArray = explode(';', $value);
         $propResultArray = array();
     function parseProperties($value) {
         $propArray = explode(';', $value);
         $propResultArray = array();
@@ -603,6 +646,10 @@ class Rfc822Header {
         return $this->processParameters($propResultArray);
     }
 
         return $this->processParameters($propResultArray);
     }
 
+    /**
+     * Fills disposition object in rfc822Header object
+     * @param string $value
+     */
     function parseDisposition($value) {
         $pos = strpos($value, ';');
         $props = '';
     function parseDisposition($value) {
         $pos = strpos($value, ';');
         $props = '';
@@ -618,6 +665,11 @@ class Rfc822Header {
         $this->disposition = $disp;
     }
 
         $this->disposition = $disp;
     }
 
+    /**
+     * Fills mlist array keys in rfc822Header object 
+     * @param string $field
+     * @param string $value
+     */
     function mlist($field, $value) {
         $res_a = array();
         $value_a = explode(',', $value);
     function mlist($field, $value) {
         $res_a = array();
         $value_a = explode(',', $value);
@@ -635,11 +687,14 @@ class Rfc822Header {
         $this->mlist[$field] = $res_a;
     }
 
         $this->mlist[$field] = $res_a;
     }
 
-    /*
-     * function to get the addres strings out of the header.
-     * Arguments: string or array of strings !
+    /**
+     * function to get the address strings out of the header.
      * example1: header->getAddr_s('to').
      * example2: header->getAddr_s(array('to', 'cc', 'bcc'))
      * example1: header->getAddr_s('to').
      * example2: header->getAddr_s(array('to', 'cc', 'bcc'))
+     * @param mixed $arr string or array of strings
+     * @param string $separator
+     * @param boolean $encoded (since 1.4.0) return encoded or plain text addresses
+     * @return string
      */
     function getAddr_s($arr, $separator = ',',$encoded=false) {
         $s = '';
      */
     function getAddr_s($arr, $separator = ',',$encoded=false) {
         $s = '';
@@ -677,6 +732,13 @@ class Rfc822Header {
         return $s;
     }
 
         return $s;
     }
 
+    /**
+     * function to get the array of addresses out of the header.
+     * @param mixed $arg string or array of strings
+     * @param array $excl_arr array of excluded email addresses
+     * @param array $arr array of added email addresses
+     * @return array
+     */
     function getAddr_a($arg, $excl_arr = array(), $arr = array()) {
         if (is_array($arg)) {
             foreach($arg as $argument) {
     function getAddr_a($arg, $excl_arr = array(), $arr = array()) {
         if (is_array($arg)) {
             foreach($arg as $argument) {
@@ -712,6 +774,12 @@ class Rfc822Header {
         return $arr;
     }
 
         return $arr;
     }
 
+    /**
+     * @param mixed $address array or string
+     * @param boolean $recurs
+     * @return mixed array, boolean
+     * @since 1.3.2
+     */
     function findAddress($address, $recurs = false) {
         $result = false;
         if (is_array($address)) {
     function findAddress($address, $recurs = false) {
         $result = false;
         if (is_array($address)) {
@@ -745,7 +813,7 @@ class Rfc822Header {
                     }
                 }
             }
                     }
                 }
             }
-             foreach ($this->cc as $cc) {
+            foreach ($this->cc as $cc) {
                 if ($cc->host == $srch_addr->host) {
                     if ($cc->mailbox == $srch_addr->mailbox) {
                         $results[] = $srch_addr;
                 if ($cc->host == $srch_addr->host) {
                     if ($cc->mailbox == $srch_addr->mailbox) {
                         $results[] = $srch_addr;
@@ -771,6 +839,12 @@ class Rfc822Header {
         return $result;
     }
 
         return $result;
     }
 
+    /**
+     * @param string $type0 media type
+     * @param string $type1 media subtype
+     * @return array media properties
+     * @todo check use of media type arguments
+     */
     function getContentType($type0, $type1) {
         $type0 = $this->content_type->type0;
         $type1 = $this->content_type->type1;
     function getContentType($type0, $type1) {
         $type0 = $this->content_type->type0;
         $type1 = $this->content_type->type1;