man Mail::Message::Head::ResentGroup () - header fields tracking message delivery

NAME

Mail::Message::Head::ResentGroup - header fields tracking message delivery

INHERITANCE

 Mail::Message::Head::ResentGroup
   is a Mail::Message::Head::FieldGroup
   is a Mail::Reporter

SYNOPSIS

 my $rg = Mail::Message::Head::ResentGroup->new(head => $head,
              From => 'me@home.nl', To => 'You@tux.aq');
 $head->addResentGroup($rg);

 my $rg = $head->addResentGroup(From => 'me');

 my @from = $rg->From;

 my @rgs = $head->resentGroups;
 $rg[2]->delete if @rgs > 2;

DESCRIPTION

A resent group is a set of header fields which describe one intermediate step in the message transport. Resent groups have NOTHING to do with user activety; there is no relation to the CWuser's sense of creating reply, forward, or bounce messages at all!

METHODS

Constructors

$obj->clone See Constructors in Mail::Message::Head::FieldGroup

$obj->from([HEAD|MESSAGE, OPTIONS]) WARNING: this method has two very different purposes. For backward compatibility reasons, without arguments resentFrom() is called to return the CWFrom field of this resent group. With any arguments, a list of CWMail::Message::Head::ResentGroup objects is returned, taken from the specified MESSAGE or message HEAD.

$obj->implementedTypes

Mail::Message::Head::ResentGroup->implementedTypes See Constructors in Mail::Message::Head::FieldGroup

Mail::Message::Head::ResentGroup->new([FIELDS], OPTIONS) Create an object which maintains one set of resent headers. The FIELDS are Mail::Message::Field objects from the same header. OPTIONS which start with capitals will be used to construct additional fields. These option names are prepended with CWResent-, keeping the capitization of what is specified.

 Option        Defined in       Default                
 Bcc                            undef                  
 Cc                             undef                  
 Date                           <now>                  
 Delivered-To                   undef                  
 From                           <required>             
 Message-ID                     <uniquely created>     
 Received                       <created>              
 Return-Path                    undef                  
 Sender                         undef                  
 To                             undef                  
 head                           <created automatically>
 log           L<Mail::Reporter>  C<'WARNINGS'>          
 message_head                   C<undef>               
 software      L<Mail::Message::Head::FieldGroup>  C<undef>               
 trace         L<Mail::Reporter>  C<'WARNINGS'>          
 type          L<Mail::Message::Head::FieldGroup>  C<undef>               
 version       L<Mail::Message::Head::FieldGroup>  C<undef>
. Bcc STRING|OBJECT|OBJECTS . Cc STRING|OBJECT|OBJECTS . Date STRING When this resent-group is dispatched by the resender of the message. Like the CWDate field, it is not the date and time that the message was actually transported. . Delivered-To STRING|FIELD . From STRING|OBJECT|OBJECTS . Message-ID STRING|FIELD The CWResent-Message-ID which identifies this resent group. The FIELD must contain a message id. . Received STRING The CWReceived field is the starting line for a resent group of header lines. If it is not defined, one is created using createReceived(). . Return-Path STRING|FIELD . Sender STRING|OBJECT Only permitted when more than one from address is specified. In this case, it selects one of these addresses as the main originator of the message. . To STRING|OBJECT|OBJECTS . head OBJECT The header where the data is stored in. Be dafault a Mail::Message::Head::Partial is created for you. . log LEVEL . message_head HEAD The real header of the message where this resent group is part of. The CWhead used in this class is only a container for a subset of fields. . software STRING . trace LEVEL . type STRING . version STRING

The header

$obj->add((FIELD => VALUE) | OBJECT) All fields appear only once, so CWadd() behaves as set().

$obj->addFields([FIELDNAMES]) Not applicable to resent-groups: the same name can appear in more than one group. Therefore, a FIELDNAME is sufficiently distinctive.

$obj->attach(HEAD) See The header in Mail::Message::Head::FieldGroup

$obj->delete See The header in Mail::Message::Head::FieldGroup

$obj->fieldNames See The header in Mail::Message::Head::FieldGroup

$obj->fields See The header in Mail::Message::Head::FieldGroup

$obj->head See The header in Mail::Message::Head::FieldGroup

$obj->messageHead([HEAD]) Returns (optionally after setting) the real header where this resent group belongs to. This may be undef at creation, and then later filled in when Mail::Message::Head::Complete::addResentGroup() is called.

$obj->orderedFields Returns the fields in the order as should appear in header according to rfc2822. For the CWResent- fields of the group, the order is not that important, but the CWReturn-Path, CWDelivered-To, and CWReceived must come first. Only fields mentioned in the RFC are returned.

$obj->set((FIELD => VALUE) | OBJECT) Set a FIELD to a (new) VALUE. The FIELD names which do not start with 'Resent-*' but need it will have that added. It is also an option to specify a fully prepared message field OBJECT. In any case, a field OBJECT is returned. Example:

 my $this = Mail::Message::Head::ResentGroup->new;
 $this->set(To => 'fish@tux.aq');
 $msg->addResentGroup($this);
 $msg->send;
 $msg->bounce(To => 'fish@tux.aq')->send;   # the same
 my $this = Mail::Message::Head::ResentGroup
     ->new(To => 'fish@tux.aq');

Access to the header

$obj->bcc In scalar context, the CWResent-Bcc field is returned. In list context, the addresses as specified within the bcc field are returned as Mail::Address objects. Bcc fields are not transmitted (hidden for external parties).

$obj->cc In scalar context, the CWResent-Cc field is returned. In list context, the addresses as specified within the cc field are returned as Mail::Address objects.

$obj->date Returns the CWResent-Date field, or CWundef if it was not defined.

$obj->dateTimestamp The timestamp as stored within the CWResent-Date field converted to local system time.

$obj->deliveredTo The field which describes the CWDelivered-To of this resent group.

$obj->destinations Returns a list of all addresses specified in the CWResent-To, CW-Cc, and CW-Bcc fields of this resent group.

$obj->isResentGroupFieldName(NAME)

Mail::Message::Head::ResentGroup->isResentGroupFieldName(NAME)

$obj->messageId Returns the message-ID used for this group of resent lines.

$obj->received The field which describes the CWReceived data of this resent group.

$obj->receivedTimestamp The timestamp as stored within the CWReceived field converted to local system time.

$obj->resentFrom In scalar context, the CWResent-From field is returned. In list context, the addresses as specified within the from field are returned as Mail::Address objects. For reasons of backward compatibility and consistency, the from() method will return the same as this method.

$obj->returnPath The field which describes the CWReturn-Path of this resent group.

$obj->sender In scalar context, the CWResent-Sender field is returned. In list context, the addresses as specified within the from field are returned as Mail::Address objects.

$obj->software See Access to the header in Mail::Message::Head::FieldGroup

$obj->to In scalar context, the CWResent-To field is returned. In list context, the addresses as specified within the to field are returned as Mail::Address objects.

$obj->type See Access to the header in Mail::Message::Head::FieldGroup

$obj->version See Access to the header in Mail::Message::Head::FieldGroup

Internals

$obj->collectFields([NAME]) See Internals in Mail::Message::Head::FieldGroup

$obj->createReceived([DOMAIN]) Create a recieved field for this resent group. This is automatically called if none was specified during creation of this resent group object. The content of this field is described in RFC2821 section 4.4. It could use some improvement.

$obj->detected(TYPE, SOFTWARE, VERSION) See Internals in Mail::Message::Head::FieldGroup

Error handling

$obj->AUTOLOAD See Error handling in Mail::Reporter

$obj->addReport(OBJECT) See Error handling in Mail::Reporter

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

Mail::Message::Head::ResentGroup->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK]) See Error handling in Mail::Reporter

$obj->details See Error handling in Mail::Message::Head::FieldGroup

$obj->errors See Error handling in Mail::Reporter

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

Mail::Message::Head::ResentGroup->log([LEVEL [,STRINGS]]) See Error handling in Mail::Reporter

$obj->logPriority(LEVEL)

Mail::Message::Head::ResentGroup->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->print([FILEHANDLE]) See Error handling in Mail::Message::Head::FieldGroup

$obj->report([LEVEL]) See Error handling in Mail::Reporter

$obj->reportAll([LEVEL]) See Error handling in Mail::Reporter

$obj->trace([LEVEL]) See Error handling in Mail::Reporter

$obj->warnings See Error handling in Mail::Reporter

Cleanup

$obj->DESTROY See Cleanup in Mail::Reporter

$obj->inGlobalDestruction See Cleanup in Mail::Reporter

DIAGNOSTICS

Error: Message header required for creation of ResentGroup.

It is required to know to which header the resent-group is created. Use the CWhead option. Maybe you should use Mail::Message::Head::Complete::addResentGroup() with DATA, which will organize the correct initiations for you.

Error: Package CW$package does not implement CW$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.

REFERENCES

See the MailBox website at <http://perl.overmeer.net/mailbox/> for more details.

COPYRIGHTS

Distribution version 2.063. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.

Copyright (c) 2001-2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.