unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Box::IMAP4::MessUser3Contributed Perl DocuMail::Box::IMAP4::Message(3pm)



NAME
       Mail::Box::IMAP4::Message - one message on a IMAP4 server

INHERITANCE
        Mail::Box::IMAP4::Message
          is a Mail::Box::Net::Message
          is a Mail::Box::Message
          is a Mail::Message
          is a Mail::Reporter

SYNOPSIS
        my $folder = new Mail::Box::IMAP4 ...
        my $message = $folder->message(10);

DESCRIPTION
       A "Mail::Box::IMAP4::Message" represents one message on a IMAP4 server,
       maintained by a Mail::Box::IMAP4 folder. Each message is stored as
       separate entity on the server, and maybe temporarily in your program as
       well.

METHODS
       Constructors

       $obj->clone(OPTIONS)

           See "Constructors" in Mail::Message

       Mail::Box::IMAP4::Message->new(OPTIONS)

        Option      --Defined in     --Default
        body          Mail::Message    undef
        body_type     Mail::Box::Message  Mail::Message::Body::Lines
        cache_body                     <false>
        cache_head                     <false>
        cache_labels                   <false>
        deleted       Mail::Message    <false>
        field_type    Mail::Message    undef
        folder        Mail::Box::Message  <required>
        head          Mail::Message    undef
        head_type     Mail::Message    Mail::Message::Head::Complete
        labels        Mail::Message    {}
        log           Mail::Reporter   'WARNINGS'
        messageId     Mail::Message    undef
        modified      Mail::Message    <false>
        size          Mail::Box::Message  undef
        trace         Mail::Reporter   'WARNINGS'
        trusted       Mail::Message    <false>
        unique        Mail::Box::Net::Message  <unique string>
        write_labels                   <true>

           . body => OBJECT

           . body_type => CODE|CLASS

           . cache_body => BOOLEAN

           . cache_head => BOOLEAN

           . cache_labels => BOOLEAN

               All standard IMAP labels can be cached on the local server to
               improve speed.  This has the same dangers as setting
               "write_labels" to false.  The caching starts when the first
               label of the message was read.

           . deleted => BOOLEAN

           . field_type => CLASS

           . folder => FOLDER

           . head => OBJECT

           . head_type => CLASS

           . labels => ARRAY|HASH

           . log => LEVEL

           . messageId => STRING

           . modified => BOOLEAN

           . size => INTEGER

           . trace => LEVEL

           . trusted => BOOLEAN

           . unique => STRING

           . write_labels => BOOLEAN

               When a label is changed or its value read, using label(), that
               info should be sent to the IMAP server.  But, this action could
               be superfluous, for instance because the label was already set
               or clear, and communication is expensive.  On the other hand,
               someone else may use IMAP to make changes in the same folder,
               and will get the updates too late or never...

       Constructing a message

       $obj->bounce([RG-OBJECT|OPTIONS])

           See "Constructing a message" in Mail::Message::Construct::Bounce

       Mail::Box::IMAP4::Message->build([MESSAGE|PART|BODY], CONTENT)

           See "Constructing a message" in Mail::Message::Construct::Build

       Mail::Box::IMAP4::Message->buildFromBody(BODY, [HEAD], HEADERS)

           See "Constructing a message" in Mail::Message::Construct::Build

       $obj->forward(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardAttach(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardEncapsulate(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardInline(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardNo(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardPostlude

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardPrelude

           See "Constructing a message" in Mail::Message::Construct::Forward

       $obj->forwardSubject(STRING)

           See "Constructing a message" in Mail::Message::Construct::Forward

       Mail::Box::IMAP4::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
       OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Read

       $obj->rebuild(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Rebuild

       $obj->reply(OPTIONS)

           See "Constructing a message" in Mail::Message::Construct::Reply

       $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])

           See "Constructing a message" in Mail::Message::Construct::Reply

       $obj->replySubject(STRING)

       Mail::Box::IMAP4::Message->replySubject(STRING)

           See "Constructing a message" in Mail::Message::Construct::Reply

       The message

       $obj->container

           See "The message" in Mail::Message

       $obj->copyTo(FOLDER, OPTIONS)

           See "The message" in Mail::Box::Message

       $obj->folder([FOLDER])

           See "The message" in Mail::Box::Message

       $obj->isDummy

           See "The message" in Mail::Message

       $obj->isPart

           See "The message" in Mail::Message

       $obj->messageId

           See "The message" in Mail::Message

       $obj->moveTo(FOLDER, OPTIONS)

           See "The message" in Mail::Box::Message

       $obj->print([FILEHANDLE])

           See "The message" in Mail::Message

       $obj->send([MAILER], OPTIONS)

           See "The message" in Mail::Message

       $obj->seqnr([INTEGER])

           See "The message" in Mail::Box::Message

       $obj->size

           Returns the size of this message.  If the message is still on the
           remote server, IMAP is used to ask for the size.  When the message
           is already loaded onto the local system, the size of the parsed
           message is taken.  These sizes can differ because the difference in
           line-ending representation.

       $obj->toplevel

           See "The message" in Mail::Message

       $obj->unique([STRING|undef])

           See "The message" in Mail::Box::Net::Message

       $obj->write([FILEHANDLE])

           See "The message" in Mail::Message

       The header

       $obj->bcc

           See "The header" in Mail::Message

       $obj->cc

           See "The header" in Mail::Message

       $obj->date

           See "The header" in Mail::Message

       $obj->destinations

           See "The header" in Mail::Message

       $obj->from

           See "The header" in Mail::Message

       $obj->get(FIELDNAME)

           See "The header" in Mail::Message

       $obj->guessTimestamp

           See "The header" in Mail::Message

       $obj->head([HEAD])

           See "The header" in Mail::Message

       $obj->nrLines

           See "The header" in Mail::Message

       $obj->sender

           See "The header" in Mail::Message

       $obj->study(FIELDNAME)

           See "The header" in Mail::Message

       $obj->subject

           See "The header" in Mail::Message

       $obj->timestamp

           See "The header" in Mail::Message

       $obj->to

           See "The header" in Mail::Message

       The body

       $obj->body([BODY])

           See "The body" in Mail::Message

       $obj->contentType

           See "The body" in Mail::Message

       $obj->decoded(OPTIONS)

           See "The body" in Mail::Message

       $obj->encode(OPTIONS)

           See "The body" in Mail::Message

       $obj->isMultipart

           See "The body" in Mail::Message

       $obj->isNested

           See "The body" in Mail::Message

       $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])

           See "The body" in Mail::Message

       Flags

       $obj->delete

           See "Flags" in Mail::Message

       $obj->deleted([BOOLEAN])

           See "Flags" in Mail::Message

       $obj->isDeleted

           See "Flags" in Mail::Message

       $obj->isModified

           See "Flags" in Mail::Message

       $obj->label(LABEL|PAIRS)

           With only one argument, the value related to LABEL is returned.
           With more that one argument, the list is interpreted a label-value
           PAIRS to be set.

           The IMAP protocol defines its own names for the labels, which must
           be set imediately to inform other IMAP clients which may have the
           same folder open. But that can be changed with new(write_labels).
           Some labels are translated to the corresponding IMAP system labels.

       $obj->labels

           Get the names of all labels (LIST context, not efficient in IMAP4),
           or a reference to a hash with labels.  You should only use the
           returned hash to read the labels, because changes made to it will
           not be passed to the remote server.  See labels() to set values.

       $obj->labelsToStatus

           See "Flags" in Mail::Message

       $obj->modified([BOOLEAN])

           See "Flags" in Mail::Message

       $obj->statusToLabels

           See "Flags" in Mail::Message

       The whole message as text

       $obj->file

           See "The whole message as text" in Mail::Message::Construct::Text

       $obj->lines

           See "The whole message as text" in Mail::Message::Construct::Text

       $obj->printStructure([FILEHANDLE|undef],[INDENT])

           See "The whole message as text" in Mail::Message::Construct::Text

       $obj->string

           See "The whole message as text" in Mail::Message::Construct::Text

       Internals

       $obj->clonedFrom

           See "Internals" in Mail::Message

       Mail::Box::IMAP4::Message->coerce(MESSAGE, OPTIONS)

           See "Internals" in Mail::Message

       $obj->diskDelete

           See "Internals" in Mail::Box::Message

       $obj->fetch([INFO, ...])

           Use the IMAP's "UID FETCH IMAP" command to get some data about this
           message.  The INFO request is passed to Mail::Box::IMAP4::fetch().
           Without INFO, "ALL" information is retreived and returned as a
           HASH.

       $obj->isDelayed

           See "Internals" in Mail::Message

       $obj->loadBody

           See "Internals" in Mail::Box::Net::Message

       $obj->readBody(PARSER, HEAD [, BODYTYPE])

           See "Internals" in Mail::Box::Message

       $obj->readFromParser(PARSER, [BODYTYPE])

           See "Internals" in Mail::Message

       $obj->readHead(PARSER [,CLASS])

           See "Internals" in Mail::Message

       $obj->recursiveRebuildPart(PART, OPTIONS)

           See "Internals" in Mail::Message::Construct::Rebuild

       $obj->storeBody(BODY)

           See "Internals" in Mail::Message

       $obj->takeMessageId([STRING])

           See "Internals" in Mail::Message

       $obj->writeDelayed(IMAP)

           Write all delayed information, like label changes, to the server.
           This is done under force, so should even be done for folders opened
           without write-access. This method is called indirectly by a
           Mail::Box::write() or Mail::Box::close().

           The IMAP argument is a Mail::IMAPClient which has the right folder
           already selected.

           Writing changes to the remote folder is not without hassle: IMAP4
           (or is it only Mail::IMAPClient doesn't support replacing header or
           body.  Therefore, when either of them change, the whole message is
           rewritten to the server (which is supported), and the original
           flagged for deletion.

       Error handling

       $obj->AUTOLOAD

           See "METHODS" in Mail::Message::Construct

       $obj->addReport(OBJECT)

           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Box::IMAP4::Message->defaultTrace([LEVEL]|[LOGLEVEL,
       TRACELEVEL]|[LEVEL, CALLBACK])

           See "Error handling" in Mail::Reporter

       $obj->errors

           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])

       Mail::Box::IMAP4::Message->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)

       Mail::Box::IMAP4::Message->logPriority(LEVEL)

           See "Error handling" in Mail::Reporter

       $obj->logSettings

           See "Error handling" in Mail::Reporter

       $obj->notImplemented

           See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->shortSize([VALUE])

       Mail::Box::IMAP4::Message->shortSize([VALUE])

           See "Error handling" in Mail::Message

       $obj->shortString

           See "Error handling" in Mail::Message

       $obj->trace([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->warnings

           See "Error handling" in Mail::Reporter

       Cleanup

       $obj->DESTROY

           See "Cleanup" in Mail::Message

       $obj->destruct

           See "Cleanup" in Mail::Box::Message

       $obj->inGlobalDestruction

           See "Cleanup" in Mail::Reporter

DETAILS
       Labels

       IMAP protocol flags

       Labels (or flags) are known to all folder formats, but differ how they
       are stored.  Some folder types use message header lines to keep the
       labels, other use a seperate file.  The IMAP protocol does not specify
       how the labels are kept on the server, but does specify how they are
       named.

       The label names as defined by the IMAP protocol are standardized into
       the MailBox standard to hide folder differences.  The following
       translations are always performed:

        \Seen     => seen
        \Answered => replied
        \Flagged  => flagged
        \Deleted  => deleted
        \Draft    => draft
        \Recent   => NOT old

       example: of label translations

        $imap->message(3)->label(replied => 1, draft => 0);

       will result in a IMAP protocol statements like

        A003 STORE 4 +FLAGS (\Answered)
        A003 STORE 4 -FLAGS (\Draft)

       Other labels

       Of course, your program may be in need for more labels than those
       provided by the protocol.  You can still use these: they stay locally
       (and are lost when the folder is closed).  Some IMAP4 extensions permit
       more labels than the basic RFC, but that is not yet supported by this
       implementation.

       Caching labels

       When you ask for one or more flags of a message more than once, you may
       improve the overall performance by setting new(cache_labels) to "YES".
       However, this may cause inconsistencies when multiple clients use the
       same folder on the IMAP server.

       You may also delay the label updates to the server until the folder is
       closed (or for ever when read-only is required).  When
       Mail::Box::write() or Mail::Box::close() is called, it is decided
       whether to throw all changes away or write after all.

DIAGNOSTICS
       Error: Cannot coerce a $class object into a $class object

       Error: Cannot include forward source as $include.

           Unknown alternative for the forward(include).  Valid choices are
           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".

       Error: Cannot include reply source as $include.

           Unknown alternative for the "include" option of reply().  Valid
           choices are "NO", "INLINE", and "ATTACH".

       Error: Method bounce requires To, Cc, or Bcc

           The message bounce() method forwards a received message off to
           someone else without modification; you must specified it's new
           destination.  If you have the urge not to specify any destination,
           you probably are looking for reply(). When you wish to modify the
           content, use forward().

       Error: Method forwardAttach requires a preamble

       Error: Method forwardEncapsulate requires a preamble

       Error: No address to create forwarded to.

           If a forward message is created, a destination address must be
           specified.

       Error: No default mailer found to send message.

           The message send() mechanism had not enough information to
           automatically find a mail transfer agent to sent this message.
           Specify a mailer explicitly using the "via" options.

       Error: No rebuild rule $name defined.

       Error: Only build() Mail::Message's; they are not in a folder yet

           You may wish to construct a message to be stored in a some kind of
           folder, but you need to do that in two steps.  First, create a
           normal Mail::Message, and then add it to the folder.  During this
           Mail::Box::addMessage() process, the message will get coerce()-d
           into the right message type, adding storage information and the
           like.

       Error: Package $package does not implement $method.

           Fatal error: the specific package (or one of its superclasses) does
           not implement this method where it should. This message means that
           some other related classes do implement this method however the
           class at hand does not.  Probably you should investigate this and
           probably inform the author of the package.

       Error: Unable to read delayed body.

       Error: Unable to read delayed head.

       Error: coercion starts with some object

SEE ALSO
       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 by Mark Overmeer. For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html



perl v5.10.0                      2008-04-28    Mail::Box::IMAP4::Message(3pm)