Subversion-Projekte lars-tiefland.php_share

<?php

//\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

//\\\       \\\\\\\\|                                                           \\

//\\\ @@    @@\\\\\\| Mail_IMAPv2                                               \\

//\\ @@@@  @@@@\\\\\|___________________________________________________________\\

//\\\@@@@| @@@@\\\\\|                                                           \\

//\\\ @@ |\\@@\\\\\\|(c) Copyright 2004-2005 Richard York, All rights Reserved  \\

//\\\\  ||   \\\\\\\|___________________________________________________________\\

//\\\\  \\_   \\\\\\|Redistribution and use in source and binary forms, with or \\

//\\\\\        \\\\\|without modification, are permitted provided that the      \\

//\\\\\  ----  \@@@@|following conditions are met:                              \\

//@@@@@\       \@@@@|                                                           \\

//@@@@@@\     \@@@@@| o Redistributions of source code must retain the above    \\

//\\\\\\\\\\\\\\\\\\|   copyright notice, this list of conditions and the       \\

//                      following disclaimer.                                   \\

//  o Redistributions in binary form must reproduce the above copyright notice, \\

//    this list of conditions and the following disclaimer in the documentation \\

//    and/or other materials provided with the distribution.                    \\

//  o The names of the authors may not be used to endorse or promote products   \\

//    derived from this software without specific prior written permission.     \\

//                                                                              \\

//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" \\

//  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE   \\

//  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE  \\

//  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE    \\

//  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR      \\

//  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF        \\

//  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS    \\

//  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN     \\

//  CONTRACT, STRICT LIABILITY, OR TORT  (INCLUDING NEGLIGENCE OR OTHERWISE)    \\

//  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE  \\

//  POSSIBILITY OF SUCH DAMAGE.                                                 \\

//\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

require_once 'PEAR/ErrorStack.php';

define('Mail_IMAPv2_BODY',                                0);

define('Mail_IMAPv2_LITERAL',                             1);

define('Mail_IMAPv2_LITERAL_DECODE',                      2);

define('Mail_IMAPv2_ERROR',                               1);

define('Mail_IMAPv2_ERROR_ARGUMENT_REQUIRES_ARRAY',       2);

define('Mail_IMAPv2_ERROR_INVALID_OPTION',                3);

define('Mail_IMAPv2_ERROR_INVALID_PID',                   4);

define('Mail_IMAPv2_ERROR_INVALID_ACTION',                5);

define('Mail_IMAPv2_NOTICE',                              100);

define('Mail_IMAPv2_NOTICE_FALLBACK_PID',                 102);

define('Mail_IMAPv2_FATAL',                               200);

/**

* Mail_IMAPv2 provides a flexible API for connecting to and retrieving

* mail from mailboxes using the IMAP, POP3 or NNTP mail protocols.

* Connection to a mailbox is acheived through the c-client extension

* to PHP (http://www.php.net/imap). Meaning installation of the

* c-client extension is required to use Mail_IMAPv2.

*

* Mail_IMAPv2 can be used to retrieve the contents of a mailbox,

* whereas it may serve as the backend for a webmail application or

* mailing list manager.

*

* Since Mail_IMAPv2 is an abstracted object, it allows for complete

* customization of the UI for any application.

*

* By default Mail_IMAPv2 parses and retrieves information about

* multipart message in a threaded fashion similar to MS Outlook, e.g.

* only top level attachments are retrieved initially, then when message

* part id and message id are passed to Mail_IMAPv2, it retrieves

* attachments and information relevant to that message part.

* {@link getParts} can be supplied an argument to turn off threading,

* whereas all parts are retrieved at once.

*

* Mail_IMAPv2 also, by default retrieves the alternative message parts

* of multipart messages. This is most useful for debugging

* applications that send out multipart mailers where both a text/html

* and alterntaive text/plain part are included. This can also be

* turned off by supplying an additional argument to {@link getParts}.

*

* Mail_IMAPv2 always searches for a text/html part to display as the primary

* part. This can be reversed so that it always looks for a text/plain part

* initially by supplying the necessary arguments to {@link getParts},

* and {@link getBody}.

*

* PLEASE REPORT BUGS FOLLOWING THE GUIDELINES AT:

*   http://www.smilingsouls.net/Mail_IMAP

*

* @author       Richard York <rich_y@php.net>

* @category     Mail

* @package      Mail_IMAPv2

* @license      BSD

* @version      0.2.0

* @copyright    (c) Copyright 2004, Richard York, All Rights Reserved.

* @since        PHP 4.2.0

* @since        C-Client 2001

* @tutorial     http://www.smilingsouls.net/Mail_IMAP

*

* @example      docs/examples/IMAP.inbox.php

*   Mail_IMAPv2 Inbox

*

* @example      docs/examples/IMAP.message_viewer.php

*   Mail_IMAPv2 Message

*

* @example      docs/examples/IMAP.part_viewer.php

*   Mail_IMAPv2 Message

*

* @example      docs/examples/IMAP.connection_wizard.php

*   Mail_IMAPv2 Connection Wizard

*

* @example      docs/examples/IMAP.connection_wizard_example.php

*   Mail_IMAPv2 Connection Wizard

*/

class Mail_IMAPv2 {

    /**

    * Contains an instance of the PEAR_ErrorStack object.

    * @var      object $error

    * @access   public

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/error

    */

    var $error;

    /**

    * Contains the imap resource stream.

    * @var     resource $mailbox

    * @access  public

    * @see     Mail_IMAPv2

    * @see     open

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/mailbox

    */

    var $mailbox;

    /**

     * Contains information about the current mailbox.

     * @var     array $mailboxInfo

     * @access  public

     * @see     connect

     * @see     getMailboxInfo

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/mailboxInfo

     */

    var $mailboxInfo = array();

    /**

     * Set flags for various imap_* functions.

     *

     * Use associative indices to indicate the imap_* function to set flags for,

     *  create the indice omitting the 'imap_' portion of the function name.

     *  see: {@link setOptions} for more information.

     *

     * @var     array $option

     * @access  public

     * @see     setOptions

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/setOptions

     */

    var $option = array();

    /**

     * Contains various information returned by {@link imap_fetchstructure}.

     * The object returned by imap_fetchstructure stored in $this->structure[$mid]['obj'].

     *

     * @var     array $_structure

     * @access  public

     * @see     _declareParts

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/structure

     */

    var $structure = array();

    /**

     * Contains various information about a message, separates inline parts from

     * attachments and contains the default part id for each message.

     *

     * @var     array $msg

     * @access  public

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/msg

     */

    var $msg = array();

    /**

     * (array)(mixed) Associative array containing information

     * gathered by {@link imap_headerinfo} or

     * {@link imap_rfc822_parse_headers}.

     *

     * @var    header array $header

     * @see     getHeaders

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/header

     */

    var $header = array();

    /**

     * (string) contains the various possible data types.

     * @var     array $_dataTypes

     * @access  private

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_dataTypes

     */

    var $_dataTypes = array(

    	'text',

        'multipart',

        'message',

        'application',

        'audio',

        'image',

        'video',

        'other'

    );

    /**

     * (string) Contains the various possible encoding types.

     * @var     array $_encodingTypes

     * @access  private

     * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_encodingTypes

     */

    var $_encodingTypes = array(

    	'7bit',

        '8bit',

        'binary',

        'base64',

        'quoted-printable',

        'other'

    );

    /**

    * (string) Contains the fields searched for and added to inline and attachment part

    * arrays. These are the 'in' and 'at' associative indices of the $msg member variable.

    * @var    array $fields

    * @access public

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/fields

    */

    var $fields = array(

    	'fname',

        'pid',

        'ftype',

        'fsize',

        'has_at',

        'charset',

        'cid'

    );

    /**

    * Constructor. Optionally set the IMAP resource stream.

    *

    * If IMAP connection arguments are not supplied, returns null.  Accepts a URI

    * abstraction of the standard imap_open connection argument (see {@link connect})

    * or the imap resource indicator.

    *

    * If the optional flags argument of imap_open needs to be set, then {@link connect}

    * should be called after either setting the {@link $option} member variable or

    * calling {@link setOptions}.

    *

    * Since Mail_IMAPv2 0.1.0 creates an instance of PEAR_ErrorStack.

    *  $options argument became $get_info argument see {@link connect}.

    *

    * @param     string         $connection  (optional) server URI | imap resource identifier

    * @param     int            $action

    *

    * @tutorial  http://www.smilingsouls.net/?content=Mail_IMAP/Mail_IMAP

    * @access    public

    * @return    BOOL|null|PEAR_Error

    * @see       connect

    * @see       imap_open

    */

    function Mail_IMAPv2($connection = null, $get_info = true)

    {

        $this->error = new PEAR_ErrorStack('Mail_IMAPv2');

        if (!empty($connection) && is_resource($connection)) {

            if (get_resource_type($connection) == 'imap') {

                $this->mailbox = $connection;

            } else {

                $this->error->push(

                	Mail_IMAPv2_ERROR,

                	'error',

                	null,

                	'Invalid imap resource passed to constructor.'

                );

            }

        } else if (!empty($connection)) {

            $this->connect($connection, $get_info);

        }

    }

    /**

    * @todo Finish writing this method, and test it.

    */

    function errorTemplate()

    {

        return array(

            // Generic Error

            Mail_IMAPv2_ERROR                           => '%message%',

            Mail_IMAPv2_ERROR_ARGUMENT_REQUIRES_ARRAY   => 'Argument \'%arg%\' must be an array.',

            Mail_IMAPv2_ERROR_INVALID_OPTION            => 'Indice \'%indice%\' for argument \'%arg%\' is not a valid option.',

            Mail_IMAPv2_ERROR_INVALID_PID               => 'Supplied part id \'%pid%\' is not valid.',

            Mail_IMAPv2_ERROR_INVALID_ACTION            => 'Action \'%action%\' is not a valid action for the \'%arg%\' argument.',

            Mail_IMAPv2_NOTICE_FALLBACK_PID             => 'Fallback PID used. A fallback PID is used in the event that Mail_IMAPv2 is not able to find a valid text/plain or text/html message part. The MIME type for the fallback pid is %ftype%'

        );

    }

    /**

    * Wrapper method for {@link imap_open}.  Accepts a URI abstraction in

    * the following format: imap://user:pass@mail.example.com:143/INBOX#notls

    * instead of the standard connection arguments used in imap_open.

    * Replace the protocol with one of pop3|pop3s imap|imaps nntp|nntps.

    * Place intial folder in the file path portion, and optionally append

    * tls|notls|novalidate-cert in the anchor portion of the URL.  A port

    * number is optional, however, leaving it off could lead to a serious

    * degradation in preformance.

    *

    * Since Mail_IMAPv2 0.1.0 the $options argument became the $get_info argument.

    * constants for action were removed and the argument is now a BOOL toggle.

    *

    * @param    string           $uri   server URI

    * @param    bool             $get_info

    *   (optional) true by default. If true, make a call to {@link getMailboxInfo}

    *   if false do not call {@link getMailboxInfo}

    * @return   BOOL

    * @tutorial http://www.smilingsouls.net/index.php?content=Mail_IMAP/connect

    * @access   public

    * @see      imap_open

    */

    function connect($uri, $get_info = true)

    {

        if (!class_exists('Net_URL') && !@include_once('Net/URL.php')) {

			$this->error->push(Mail_IMAPv2_ERROR, 'error', null, 'Inclusion of Net_URL not successful.');

            return false;

        }

        $opt = (isset($this->option['open']))? $this->option['open'] : null;

        $net_url =& new Net_URL($uri);

        $uri  = '{'.$net_url->host;

        if (!empty($net_url->port)) {

            $uri .= ':'.$net_url->port;

        }

        $secure   = ('tls' == substr($net_url->anchor, 0, 3))? '' : '/ssl';

        $uri .= ('s' == (substr($net_url->protocol, -1)))? '/'.substr($net_url->protocol, 0, 4).$secure : '/'.$net_url->protocol;

        if (!empty($net_url->anchor)) {

            $uri .= '/'.$net_url->anchor;

        }

        $uri .= '}';

        $this->mailboxInfo['Mail_IMAPv2']['version'] = 'Mail_IMAPv2 0.2.0 Beta';

        $this->mailboxInfo['host'] = $uri;

        // Trim off the leading slash '/'

        if (!empty($net_url->path)) {

            $this->mailboxInfo['folder'] = substr($net_url->path, 1, (strlen($net_url->path) - 1));

            $uri .= $this->mailboxInfo['folder'];

        }

        $this->mailboxInfo['user'] = urldecode($net_url->user);

        if (false === ($this->mailbox = @imap_open($uri, urldecode($net_url->user), $net_url->pass, $opt))) {

            $this->error->push(

            	Mail_IMAPv2_ERROR,

            	'error',

            	null,

            	'Unable to build a connection to the specified mail server.'

            );

            $ret = false;

        } else {

            $ret = true;

        }

        // get mailbox info

        if ($get_info) {

            $this->getMailboxInfo(false);

        }

        return $ret;

    }

    /*

    * Adds to the {@link $mailboxInfo} member variable information about the current

    * mailbox from {@link imap_mailboxmsginfo}.

    *

    * Note: This method is automatically called on by default by {@link connect}.

    *

    * @param    string           $connect   server URL

    * @param    bool             $get_info

    *   (optional) true by default. If true, make a call to {@link getMailboxInfo}

    *   if false do not call {@link getMailboxInfo}

    *

    * @return   VOID|Array

    * @access   public

    * @see      imap_open

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getMailboxInfo

    */

    function getMailboxInfo($ret = true)

    {

        // It's possible that this function has already been called by $this->connect

        // If so, the 'Mailbox' indice will already exist and the user just wants

        // the contents of the mailboxInfo member variable.

        if (!isset($this->mailboxInfo['Mailbox'])) {

            $this->mailboxInfo = @array_merge(

            	$this->mailboxInfo,

            	get_object_vars(

            		imap_mailboxmsginfo($this->mailbox)

            	)

            );

        }

        return ($ret)? $this->mailboxInfo : true;

    }

    /**

    * Set the $option member variable, which is used to specify optional imap_* function

    * arguments (labeled in the manual as flags or options e.g. FT_UID, OP_READONLY, etc).

    *

    * <b>Example:</b>

    * <code>

    *    $msg->setOptions(array('body', 'fetchbody', 'fetchheader'), 'FT_UID');

    * </code>

    *

    * This results in imap_body, imap_fetchbody and imap_fetchheader being passed the FT_UID

    * option in the flags/options argument where ever these are called on by Mail_IMAPv2.

    *

    * Note: this method only sets optional imap_* arguments labeled as flags/options.

    *

    * @param    array          $options - function names to pass the arugument to

    * @param    string         $constant   - constant name to pass.

    * @return   PEAR_Error|true

    * @access   public

    * @see      $option

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/setOptions

    */

    function setOptions($options, $constant)

    {

        if (is_array($options) && !empty($options)) {

            foreach ($options as $value) {

                if (!$this->option[$value] = @constant($constant)) {

                    $this->error->push(

                    	Mail_IMAPv2_ERROR,

                    	'error',

                    	null,

                    	'The constant: '.$constant.' is not defined!'

                    );

                }

            }

        } else {

            $this->error->push(

            	Mail_IMAPv2_ERROR_ARGUMENT_REQUIRES_ARRAY,

            	'error',

            	array('arg' => '$options')

            );

            return false;

        }

        return true;

    }

    /**

    * Wrapper method for {@link imap_close}.  Close the IMAP resource stream.

    *

    * @return   BOOL

    * @access   public

    * @tutorial http://www.smilingsouls.net/index.php?content=Mail_IMAP/close

    * @see      imap_close

    */

    function close()

    {

        $opt = (isset($this->option['close']))? $this->option['close'] : null;

        return @imap_close($this->mailbox, $opt);

    }

    /**

    * Wrapper method for {@link imap_num_msg}.

    *

    * @return   int mailbox message count

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/messageCount

    * @access   public

    * @see      imap_num_msg

    */

    function messageCount()

    {

        return @imap_num_msg($this->mailbox);

    }

    /**

    * Gather message information returned by {@link imap_fetchstructure} and recursively iterate

    * through each parts array.  Concatenate part numbers in the following format `1.1`

    * each part id is separated by a period, each referring to a part or subpart of a

    * multipart message.  Create part numbers as such that they are compatible with

    * {@link imap_fetchbody}.

    *

    * @param    int           &$mid         message id

    * @param    array         $sub_part     recursive

    * @param    string        $sub_pid      recursive parent part id

    * @param    int           $n            recursive counter

    * @param    bool          $is_sub_part  recursive

    * @param    bool          $skip_part    recursive

    * @return   mixed

    * @access   protected

    * @see      imap_fetchstructure

    * @see      imap_fetchbody

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_declareParts

    */

    function _declareParts(&$mid, $sub_part = null, $sub_pid = null, $n = 0, $is_sub_part = false, $skip_part = false, $last_was_signed = false)

    {

        if (!is_array($sub_part)) {

            $opt = (isset($this->option['fetchstructure']))? $this->option['fetchstructure'] : null;

            $this->structure[$mid]['obj'] = @imap_fetchstructure($this->mailbox, $mid, $opt);

        }

        if (isset($this->structure[$mid]['obj']->parts) || is_array($sub_part)) {

            if (!$is_sub_part) {

                $parts = $this->structure[$mid]['obj']->parts;

            } else {

                $parts = $sub_part;

                $n++;

            }

            for ($p = 0, $i = 1; $p < count($parts); $n++, $p++, $i++) {

                // Skip the following...

                // multipart/mixed!

                // subsequent multipart/alternative if this part is message/rfc822

                // multipart/related

                //

                // Have noticed the existence of several other multipart/* types of messages

                // but have yet had the opportunity to test on those.

                $ftype = (empty($parts[$p]->type))?

                    $this->_dataTypes[0].'/'.strtolower($parts[$p]->subtype)

                :

                	$this->_dataTypes[$parts[$p]->type].'/'.strtolower($parts[$p]->subtype);

                $this_was_signed	= ($ftype == 'multipart/signed')? true : false;

                $skip_next			= ($ftype == 'message/rfc822')?   true : false;

                if (

                	$ftype == 'multipart/mixed' && ($last_was_signed || $skip_part) ||

                	$ftype == 'multipart/signed' ||

                	$skip_part && $ftype == 'multipart/alternative' ||

                	$ftype == 'multipart/related' && count($parts) == 1

               	) {

                    $n--;

                    $skipped = true;

                } else {

                    $skipped = false;

                    $this->structure[$mid]['pid'][$n]       = ($is_sub_part == false)? (string) "$i" : (string) "$sub_pid.$i";

                    $this->structure[$mid]['ftype'][$n]     = $ftype;

                    $this->structure[$mid]['encoding'][$n]  = (empty($parts[$p]->encoding))? $this->_encodingTypes[0] : $this->_encodingTypes[$parts[$p]->encoding];

                    $this->structure[$mid]['fsize'][$n]     = (!isset($parts[$p]->bytes) || empty($parts[$p]->bytes))? 0 : $parts[$p]->bytes;

                    // Get extra parameters.

                    if ($parts[$p]->ifparameters) {

                        foreach ($parts[$p]->parameters as $param) {

                            $this->structure[$mid][strtolower($param->attribute)][$n] = strtolower($param->value);

                        }

                    }

                    // Force inline disposition if none is present

                    if ($parts[$p]->ifdisposition) {

                        $this->structure[$mid]['disposition'][$n] = strtolower($parts[$p]->disposition);

                        if ($parts[$p]->ifdparameters) {

                            foreach ($parts[$p]->dparameters as $param) {

                                if (strtolower($param->attribute) == 'filename') {

                                    $this->structure[$mid]['fname'][$n] = $param->value;

                                    break;

                                }

                            }

                        }

                    } else {

                        $this->structure[$mid]['disposition'][$n] = 'inline';

                    }

                    if ($parts[$p]->ifid) {

                        $this->structure[$mid]['cid'][$n] = $parts[$p]->id;

                    }

                }

                if (isset($parts[$p]->parts) && is_array($parts[$p]->parts)) {

                    if (!$skipped) {

                        $this->structure[$mid]['has_at'][$n] = true;

                    }

                    $n = $this->_declareParts($mid, $parts[$p]->parts, $this->structure[$mid]['pid'][$n], $n, true, $skip_next, $this_was_signed);

                }

                else if (!$skipped) {

                	$this->structure[$mid]['has_at'][$n] = false;

                }

            }

            if ($is_sub_part) {

                return $n;

            }

         } else {

             // $parts is not an array... message is flat

            $this->structure[$mid]['pid'][0] = 1;

            if (empty($this->structure[$mid]['obj']->type)) {

                $this->structure[$mid]['obj']->type = (int) 0;

            }

            if (isset($this->structure[$mid]['obj']->subtype)) {

                $this->structure[$mid]['ftype'][0] = $this->_dataTypes[$this->structure[$mid]['obj']->type].'/'.strtolower($this->structure[$mid]['obj']->subtype);

            }

            if (empty($this->structure[$mid]['obj']->encoding)) {

                $this->structure[$mid]['obj']->encoding = (int) 0;

            }

            $this->structure[$mid]['encoding'][0] = $this->_encodingTypes[$this->structure[$mid]['obj']->encoding];

            if (isset($this->structure[$mid]['obj']->bytes)) {

                $this->structure[$mid]['fsize'][0] = strtolower($this->structure[$mid]['obj']->bytes);

            }

            $this->structure[$mid]['disposition'][0]    = 'inline';

            $this->structure[$mid]['has_at'][0] = false;

            // Go through the parameters, if any

            if (isset($this->structure[$mid]['obj']->ifparameters) && $this->structure[$mid]['obj']->ifparameters) {

                foreach ($this->structure[$mid]['obj']->parameters as $param) {

                    $this->structure[$mid][strtolower($param->attribute)][0] = $param->value;

                }

            }

        }

        return;

    }

    /**

    * Checks if the part has been parsed, if not calls on _declareParts to

    * parse the message.

    *

    * @param    int          &$mid         message id

    * @param    bool         $checkPid

    * @return   void

    * @access   protected

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_checkIfParsed

    */

    function _checkIfParsed(&$mid, $checkPid = true, $get_mime = 'text/html')

    {

        if (!isset($this->structure[$mid]['pid'])) {

           $this->_declareParts($mid);

        }

        if ($checkPid == true && !isset($this->msg[$mid]['pid'])) {

           $this->_getDefaultPid($mid, $get_mime);

        }

        return;

    }

    /**

    * sets up member variables containing inline parts and attachments for a specific

    * part in member variable arrays beginning with 'in' and 'attach'. If inline parts

    * are present, sets {@link $inPid}, {@link $inFtype}, {@link $inFsize},

    * {@link $inHasAttach}, {@link $inInlineId} (if an inline CID is specified). If

    * attachments are present, sets, {@link $attachPid}, {@link $attachFsize},

    * {@link $attachHasAttach}, {@link $attachFname} (if a filename is present, empty

    * string otherwise).

    *

    * @param    int           &$mid         message id

    * @param    int           &$pid         part id

    * @param    bool          $ret

    *   false by default, if true returns the contents of the $in* and $attach* arrays.

    *   If false method returns BOOL.

    *

    * @param    string        $args         (optional)

    *   Associative array containing optional extra arguments. The following are the

    *   possible indices.

    *

    *       $args['get_mime'] STRING

    *           Values: text/plain|text/html, text/html by default. The MIME type for

    *           the part to be displayed by default for each level of nesting.

    *

    *       $agrs['get_alternative'] BOOL

    *           If true, includes the alternative part of a multipart/alternative

    *           message in the $in* array. If veiwing text/html part by default this

    *           places the text/plain part in the $in* (inline attachment array).

    *

    *       $args['retrieve_all'] BOOL

    *           If true, gets all the message parts at once, this option will index

    *           the entire message in the $in* and $attach* member variables regardless

    *           of nesting (method indexes parts relevant to the current level of

    *           nesting by default).

    *

    * @return   BOOL|Array

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getParts

    * @access   public

    * @since    PHP 4.2.0

    */

    function getParts(&$mid, $pid = '0', $ret = false, $args = array())

    {

        if (!isset($args['get_mime'])) {

            $args['get_mime'] = 'text/html';

        }

        if (!isset($args['get_alternative'])) {

            $args['get_alternative'] = true;

        }

        $this->_checkIfParsed($mid, true, $args['get_mime']);

        if ($pid === '0') {

            $pid = $this->msg[$mid]['pid'];

        }

        if (count($this->structure[$mid]['pid']) == 1 && !isset($this->structure[$mid]['fallback'][0])) {

            return true;

        }

        // retrieve key for this part, so that the information may be accessed

        if (false !== ($i = array_search((string) $pid, $this->structure[$mid]['pid']))) {

            if (isset($args['retrieve_all']) && $args['retrieve_all'] == true) {

                $this->_scanMultipart($mid, $pid, $i, $args['get_mime'], 'add', 'none', 2, $args['get_alternative']);

            } else {

                if ($pid == $this->msg[$mid]['pid']) {

                    $this->_scanMultipart($mid, $pid, $i, $args['get_mime'], 'add', 'top', 2, $args['get_alternative']);

                } else if ($this->structure[$mid]['ftype'][$i] == 'message/rfc822') {

                    $this->_scanMultipart($mid, $pid, $i, $args['get_mime'], 'add', 'all', 1, $args['get_alternative']);

                }

            }

        } else {

            $this->error->push(Mail_IMAPv2_ERROR_INVALID_PID, 'error', array('pid' => $pid));

            return false;

        }

        return ($ret)? $this->msg[$mid] : true;

    }

    /**

    * Finds message parts relevant to the message part currently being displayed or

    * looks through a message and determines which is the best body to display.

    *

    * @param    int           &$mid         message id

    * @param    int           &$pid         part id

    * @param    int           $i            offset indice correlating to the pid

    * @param    str           $MIME         one of text/plain or text/html the default MIME to retrieve.

    * @param    str           $action       one of add|get

    * @param    str           $look_for     one of all|multipart|top|none

    * @param    int           $pid_add      determines the level of nesting.

    * @param    bool          $get_alternative

    *   Determines whether the program retrieves the alternative part in a

    *   multipart/alternative message.

    *

    * @return   string|false

    * @access   private

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_scanMultipart

    */

    function _scanMultipart(&$mid, &$pid, &$i, $MIME, $action = 'add', $look_for = 'all', $pid_add = 1, $get_alternative = true)

    {

        // Find subparts, create variables

        // Create inline parts first, and attachments second

        // Get all top level parts, with the exception of the part currently being viewed

        // If top level part contains multipart/alternative go into that subpart to

        // retrieve the other inline message part to display

        // If this part is message/rfc822 get subparts that begin with this part id

        // Skip multipart/alternative message part

        // Find the displayable message, get text/plain part if $getInline is true

        if ($action == 'add') {

           $excludeMIME = $MIME;

           $MIME        = ($excludeMIME == 'text/plain')? 'text/html' : 'text/plain';

           $in          = 0;

           $a           = 0;

        } else if ($action == 'get') {

           $excludeMIME = null;

        }

        $pid_len      = strlen($pid);

        $this_nesting = count(explode('.', $pid));

        foreach ($this->structure[$mid]['pid'] as $p => $id) {

            // To look at the next level of nesting one needs to determine at which level

            // of nesting the program currently resides, this needs to be independent of the

            // part id length, since part ids can get into double digits (let's hope they

            // don't get into triple digits!)

            // To accomplish this we'll explode the part id on the dot to get a count of the

            // nesting, then compare the string with the next level in.

            $nesting = count(explode('.', $this->structure[$mid]['pid'][$p]));

            switch ($look_for) {

                case 'all':

                {

                    $condition = (($nesting == ($this_nesting + 1)) && $pid == substr($this->structure[$mid]['pid'][$p], 0, $pid_len));

                    break;

                }

                case 'multipart':

                {

                    $condition = (($nesting == ($this_nesting + 1)) && ($pid == substr($this->structure[$mid]['pid'][$p], 0)));

                    break;

                }

                // Used if *all* parts are being retrieved

                case 'none':

                {

                    $condition = true;

                    break;

                }

                // To gaurantee a top-level part, detect whether a period appears in the pid string

                case 'top':

                default:

                {

                    if ($this->_isMultipart($mid, 'related') || $this->_isMultipart($mid, 'mixed')) {

                        $condition = (!stristr($this->structure[$mid]['pid'][$p], '.') || ($nesting == 2) && substr($this->msg[$mid]['pid'], 0, 1) == substr($this->structure[$mid]['pid'][$p], 0, 1));

                    } else {

                        $condition = (!stristr($this->structure[$mid]['pid'][$p], '.'));

                    }

                }

            }

            if ($condition == true) {

                if ($this->structure[$mid]['ftype'][$p] == 'multipart/alternative' || $this->structure[$mid]['ftype'][$p] == 'multipart/mixed') {

                    foreach ($this->structure[$mid]['pid'] as $mp => $mpid) {

                        // Part must begin with last matching part id and be two levels in

                        $sub_nesting = count(explode('.', $this->structure[$mid]['pid'][$p]));

                        if (

                        	$this->structure[$mid]['ftype'][$mp] == $MIME &&

                            $get_alternative == true &&

                            ($sub_nesting == ($this_nesting + $pid_add)) &&

                            ($pid == substr($this->structure[$mid]['pid'][$mp], 0, strlen($this->structure[$mid]['pid'][$p])))

                        ) {

                            if ($action == 'add') {

                                 $this->_addPart($in, $mid, $mp, 'in');

                                 break;

                            } else if ($action == 'get' && !isset($this->structure[$mid]['fname'][$mp]) && empty($this->structure[$mid]['fname'][$mp])) {

                                return $this->structure[$mid]['pid'][$mp];

                            }

                        } else if ($this->structure[$mid]['ftype'][$mp] == 'multipart/alternative' && $action == 'get') {

                            // Need to match this PID to next level in

                            $pid          = (string) $this->structure[$mid]['pid'][$mp];

                            $pid_len      = strlen($pid);

                            $this_nesting = count(explode('.', $pid));

                            $pid_add       = 2;

                            continue;

                        }

                    }

                } else if ($this->structure[$mid]['disposition'][$p] == 'inline' && $this->structure[$mid]['ftype'][$p] != 'multipart/related' && $this->structure[$mid]['ftype'][$p] != 'multipart/mixed') {

                    if ((

                    	  $action == 'add' &&

                          $this->structure[$mid]['ftype'][$p] != $excludeMIME &&

                          $pid != $this->structure[$mid]['pid'][$p]

                       	) || (

                          $action == 'add' &&

                          $this->structure[$mid]['ftype'][$p] == $excludeMIME &&

                          isset($this->structure[$mid]['fname'][$p]) &&

                          $pid != $this->structure[$mid]['pid'][$p]

                       	) || (

                          $action == 'add' && isset($this->structure[$mid]['fallback'][0])

                       )) {

                        $this->_addPart($in, $mid, $p, 'in');

                    } else if ($action == 'get' && $this->structure[$mid]['ftype'][$p] == $MIME && !isset($this->structure[$mid]['fname'][$p])) {

                        return $this->structure[$mid]['pid'][$p];

                    }

                } else if ($action == 'add' && $this->structure[$mid]['disposition'][$p] == 'attachment') {

                    $this->_addPart($a, $mid, $p, 'at');

                }

            }

        }

        return false;

    }

    /**

    * Determines whether a message contains a multipart/(insert subtype here) part.

    * Only called on by $this->_scanMultipart

    *

    * @return   BOOL

    * @access   private

    * @see      _scanMultipart

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_isMultipart

    */

    function _isMultipart($mid, $subtype)

    {

        $ret = $this->extractMIME($mid, array('multipart/'.$subtype));

        return (!empty($ret) && is_array($ret) && count($ret) >= 1)? true : false;

    }

    /**

    * Looks to see if this part has any inline parts associated with it.

    * It looks up the message tree for parts with CID entries and

    * indexes those entries, whereas an algorithm may be ran to replace

    * inline CIDs with a part viewer.

    *

    * @param   int      &$mid          message id

    * @param   string   &$pid          part id

    * @param   array    $secureMIME    array of acceptable CID MIME types.

    *

    * The $secureMIME argument allows you to limit the types of files allowed

    * in a multipart/related message, for instance, to prevent a browser from

    * automatically initiating download of a part that could contain potentially

    * malicious code.

    *

    * Suggested MIME types:

    * text/plain, text/html, text/css, image/jpeg, image/pjpeg, image/gif

    * image/png,  image/x-png, application/xml, application/xhtml+xml,

    * text/xml

    *

    * MIME types are not limited by default.

    *

    * @return  array|false

    *    On success returns an array of parts associated with the current message,

    *    including the cid of the part, the part id and the MIME type.

    *

    * @access  public

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getRelatedParts

    */

    function getRelatedParts(&$mid, &$pid, $secureMIME = array())

    {

        // Check to see if this part has already been parsed

        $this->_checkIfParsed($mid);

        // Message has a PID of 1.1.2

        // Cid parts are located at the prior level of nesting at 1.x

        // From the supplied PID, go back one level of nesting.

        // Compare the first number of the supplied PID against the current PID.

        // Look for a cid entry in the structure array.

        // Index the PID and CID of the part.

        //

        // Supplied pid must correspond to a text/html part.

        if (!empty($secureMIME) && is_array($secureMIME)) {

            $this->error->push(

            	Mail_IMAPv2_ERROR_ARGUMENT_REQUIRES_ARRAY,

            	'error',

            	array(

            		'arg' => '$secureMIME',

            		'actual_value' => $secureMIME

            	)

            );

            return false;

        }

        $related = array();

        if (isset($this->structure[$mid]['pid']) && is_array($this->structure[$mid]['pid'])) {

            if (strlen($pid) > 1) {

                $nesting = count(explode('.', $pid));

                $compare = substr($pid, 0, -4);

                foreach ($this->structure[$mid]['pid'] as $i => $rpid) {

                    // This level of nesting is one above the message part

                    // The beginning of the pid string of the related part matches that of the

                    // beginning of the pid supplied

                    if (count(explode('.', $rpid)) == ($nesting - 1) && substr($rpid, 0, -2) == $compare) {

                        $this->_getCIDs($mid, $i, $secureMIME, $related);

                    }

                }

            } else if (strlen($pid) == 1) {

                // If the pid is in the first level of nesting, odds are the related parts are in the

                // sub level of nesting.

                foreach ($this->structure[$mid]['pid'] as $i => $rpid) {

                    // The part is one level under and the first number matches that

                    // of its parent part.

                    if (count(explode('.', $rpid)) == 2 && substr($rpid, 0, 1) == $pid) {

                        $this->_getCIDs($mid, $i, $secureMIME, $related);

                    }

                }

            }

        } else {

            $this->error->push(

            	Mail_IMAPv2_ERROR,

            	'error',

            	null,

            	'Message structure does not exist.'

            );

        }

        return (count($related) >= 1)? $related : false;

    }

    /**

    * Helper function for getRelatedParts

    *

    * @return void

    * @access private

    * @see    getRelatedParts

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_getCIDs

    */

    function _getCIDs(&$mid, &$i, &$secureMIME, &$related)

    {

        if ((isset($this->structure[$mid]['cid'][$i])) && (empty($secureMIME) || is_array($secureMIME) && in_array($this->structure[$mid]['ftype'][$i], $secureMIME))) {

            $related['cid'][] = $this->structure[$mid]['cid'][$i];

            $related['pid'][] = $this->structure[$mid]['pid'][$i];

            $related['ftype'][] = $this->structure[$mid]['ftype'][$i];

        }

    }

    /**

    * Destroys variables set by {@link getParts} and _declareParts.

    *

    * @param    integer  &$mid   message id

    * @return   void

    * @access   public

    * @see      getParts

    * @tutorial http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/unsetParts

    */

    function unsetParts(&$mid)

    {

        unset($this->msg[$mid]);