1=encoding utf8 2 3=head1 NAME 4 5Mail::Message::Head::ResentGroup - header fields tracking message delivery 6 7=head1 INHERITANCE 8 9 Mail::Message::Head::ResentGroup 10 is a Mail::Message::Head::FieldGroup 11 is a Mail::Reporter 12 13=head1 SYNOPSIS 14 15 use Mail::Message::Head::ResentGroup; 16 my $rg = Mail::Message::Head::ResentGroup->new(head => $head, 17 From => 'me@home.nl', To => 'You@tux.aq'); 18 $head->addResentGroup($rg); 19 20 my $rg = $head->addResentGroup(From => 'me'); 21 22 my @from = $rg->From; 23 24 my @rgs = $head->resentGroups; 25 $rg[2]->delete if @rgs > 2; 26 27=head1 DESCRIPTION 28 29A I<resent group> is a set of header fields which describe one intermediate 30step in the message transport. Resent groups B<have NOTHING to do> with 31user activety; there is no relation to the C<user's> sense of creating 32reply, forward, or bounce messages at all! 33 34Extends L<"DESCRIPTION" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"DESCRIPTION">. 35 36=head1 METHODS 37 38Extends L<"METHODS" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"METHODS">. 39 40=head2 Constructors 41 42Extends L<"Constructors" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Constructors">. 43 44=over 4 45 46=item $obj-E<gt>B<clone>() 47 48Inherited, see L<Mail::Message::Head::FieldGroup/"Constructors"> 49 50=item $obj-E<gt>B<from>( [<$head|$message>, %options] ) 51 52WARNING: this method has two very different purposes. For backward 53compatibility reasons, without arguments L<resentFrom()|Mail::Message::Head::ResentGroup/"Access to the header"> is called to 54return the C<From> field of this resent group. 55 56With any arguments, a list of C<Mail::Message::Head::ResentGroup> objects 57is returned, taken from the specified $message or message $head. 58 59=item $obj-E<gt>B<implementedTypes>() 60 61=item Mail::Message::Head::ResentGroup-E<gt>B<implementedTypes>() 62 63Inherited, see L<Mail::Message::Head::FieldGroup/"Constructors"> 64 65=item Mail::Message::Head::ResentGroup-E<gt>B<new>( [$fields], %options ) 66 67Create an object which maintains one set of resent headers. The 68$fields are L<Mail::Message::Field|Mail::Message::Field> objects from the same header. 69 70%options which start with capitals will be used to construct additional 71fields. These option names are prepended with C<Resent-*>, keeping the 72capitization of what is specified. 73 74 -Option --Defined in --Default 75 Bcc undef 76 Cc undef 77 Date <now> 78 Delivered-To undef 79 From <required> 80 Message-ID <uniquely created> 81 Received <created> 82 Return-Path undef 83 Sender undef 84 To undef 85 head <created automatically> 86 log Mail::Reporter 'WARNINGS' 87 message_head undef 88 software Mail::Message::Head::FieldGroup undef 89 trace Mail::Reporter 'WARNINGS' 90 type Mail::Message::Head::FieldGroup undef 91 version Mail::Message::Head::FieldGroup undef 92 93=over 2 94 95=item Bcc => STRING|OBJECT|OBJECTS 96 97=item Cc => STRING|OBJECT|OBJECTS 98 99=item Date => STRING 100 101When this resent-group is dispatched by the resender of the message. Like 102the C<Date> field, it is not the date and time that the message was 103actually transported. 104 105=item Delivered-To => STRING|FIELD 106 107=item From => STRING|OBJECT|OBJECTS 108 109=item Message-ID => STRING|FIELD 110 111The C<Resent-Message-ID> which identifies this resent group. The FIELD 112must contain a message id. 113 114=item Received => STRING 115 116The C<Received> field is the starting line for a resent group of header 117lines. If it is not defined, one is created using L<createReceived()|Mail::Message::Head::ResentGroup/"Internals">. 118 119=item Return-Path => STRING|FIELD 120 121=item Sender => STRING|OBJECT 122 123Only permitted when more than one from address is specified. In this case, 124it selects one of these addresses as the main originator of the message. 125 126=item To => STRING|OBJECT|OBJECTS 127 128=item head => OBJECT 129 130The header where the data is stored in. By default a 131L<Mail::Message::Head::Partial|Mail::Message::Head::Partial> is created for you. 132 133=item log => LEVEL 134 135=item message_head => HEAD 136 137The real header of the message where this resent group is part of. The 138C<head> used in this class is only a container for a subset of fields. 139 140=item software => STRING 141 142=item trace => LEVEL 143 144=item type => STRING 145 146=item version => STRING 147 148=back 149 150=back 151 152=head2 The header 153 154Extends L<"The header" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"The header">. 155 156=over 4 157 158=item $obj-E<gt>B<add>( <$field, $value> | $object ) 159 160All fields appear only once, so C<add()> behaves as L<set()|Mail::Message::Head::ResentGroup/"The header">. 161 162=item $obj-E<gt>B<addFields>( [$fieldnames] ) 163 164Not applicable to resent-groups: the same name can appear in more than 165one group. Therefore, a FIELDNAME is sufficiently distinctive. 166 167=item $obj-E<gt>B<attach>($head) 168 169Inherited, see L<Mail::Message::Head::FieldGroup/"The header"> 170 171=item $obj-E<gt>B<delete>() 172 173Inherited, see L<Mail::Message::Head::FieldGroup/"The header"> 174 175=item $obj-E<gt>B<fieldNames>() 176 177Inherited, see L<Mail::Message::Head::FieldGroup/"The header"> 178 179=item $obj-E<gt>B<fields>() 180 181Inherited, see L<Mail::Message::Head::FieldGroup/"The header"> 182 183=item $obj-E<gt>B<head>() 184 185Inherited, see L<Mail::Message::Head::FieldGroup/"The header"> 186 187=item $obj-E<gt>B<messageHead>( [$head] ) 188 189Returns (optionally after setting) the real header where this resent group 190belongs to. This may be undef at creation, and then later filled in 191when L<Mail::Message::Head::Complete::addResentGroup()|Mail::Message::Head::Complete/"Access to the header"> is called. 192 193=item $obj-E<gt>B<orderedFields>() 194 195Returns the fields in the order as should appear in header according 196to rfc2822. For the C<Resent-*> fields of the group, the order is 197not that important, but the C<Return-Path>, C<Delivered-To>, and C<Received> 198must come first. Only fields mentioned in the RFC are returned. 199 200=item $obj-E<gt>B<set>( <$field, $value> | $object ) 201 202Set a $field to a (new) $value. The $field names which do not start with 203'Resent-*' but need it will have that added. It is also an option to 204specify a fully prepared message field $object. In any case, a field 205$object is returned. 206 207example: 208 209 my $this = Mail::Message::Head::ResentGroup->new; 210 $this->set(To => 'fish@tux.aq'); 211 $msg->addResentGroup($this); 212 $msg->send; 213 214 $msg->bounce(To => 'fish@tux.aq')->send; # the same 215 216 my $this = Mail::Message::Head::ResentGroup 217 ->new(To => 'fish@tux.aq'); 218 219=back 220 221=head2 Access to the header 222 223Extends L<"Access to the header" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Access to the header">. 224 225=over 4 226 227=item $obj-E<gt>B<bcc>() 228 229In scalar context, the C<Resent-Bcc> field is returned. In list context, 230the addresses as specified within the bcc field are returned as 231L<Mail::Address|Mail::Address> objects. Bcc fields are not transmitted (hidden for 232external parties). 233 234=item $obj-E<gt>B<cc>() 235 236In scalar context, the C<Resent-Cc> field is returned. In list context, 237the addresses as specified within the cc field are returned as 238L<Mail::Address|Mail::Address> objects. 239 240=item $obj-E<gt>B<date>() 241 242Returns the C<Resent-Date> field, or C<undef> if it was not defined. 243 244=item $obj-E<gt>B<dateTimestamp>() 245 246The timestamp as stored within the C<Resent-Date> field converted to 247local system time. 248 249=item $obj-E<gt>B<deliveredTo>() 250 251The field which describes the C<Delivered-To> of this resent group. 252 253=item $obj-E<gt>B<destinations>() 254 255Returns a list of all addresses specified in the C<Resent-To>, C<-Cc>, and 256C<-Bcc> fields of this resent group. 257 258=item $obj-E<gt>B<isResentGroupFieldName>($name) 259 260=item Mail::Message::Head::ResentGroup-E<gt>B<isResentGroupFieldName>($name) 261 262=item $obj-E<gt>B<messageId>() 263 264Returns the message-ID used for this group of resent lines. 265 266=item $obj-E<gt>B<received>() 267 268The field which describes the C<Received> data of this resent group. 269 270=item $obj-E<gt>B<receivedTimestamp>() 271 272The timestamp as stored within the C<Received> field converted to 273local system time. 274 275=item $obj-E<gt>B<resentFrom>() 276 277In scalar context, the C<Resent-From> field is returned. In list 278context, the addresses as specified within the from field are 279returned as L<Mail::Address|Mail::Address> objects. 280 281For reasons of backward compatibility and consistency, the L<from()|Mail::Message::Head::ResentGroup/"METHODS"> 282method will return the same as this method. 283 284=item $obj-E<gt>B<returnPath>() 285 286The field which describes the C<Return-Path> of this resent group. 287 288=item $obj-E<gt>B<sender>() 289 290In scalar context, the C<Resent-Sender> field is returned. In list 291context, the addresses as specified within the from field are 292returned as L<Mail::Address|Mail::Address> objects. 293 294=item $obj-E<gt>B<software>() 295 296Inherited, see L<Mail::Message::Head::FieldGroup/"Access to the header"> 297 298=item $obj-E<gt>B<to>() 299 300In scalar context, the C<Resent-To> field is returned. In list context, 301the addresses as specified within the to field are returned as 302L<Mail::Address|Mail::Address> objects. 303 304=item $obj-E<gt>B<type>() 305 306Inherited, see L<Mail::Message::Head::FieldGroup/"Access to the header"> 307 308=item $obj-E<gt>B<version>() 309 310Inherited, see L<Mail::Message::Head::FieldGroup/"Access to the header"> 311 312=back 313 314=head2 Internals 315 316Extends L<"Internals" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Internals">. 317 318=over 4 319 320=item $obj-E<gt>B<collectFields>( [$name] ) 321 322Inherited, see L<Mail::Message::Head::FieldGroup/"Internals"> 323 324=item $obj-E<gt>B<createReceived>( [$domain] ) 325 326Create a received field for this resent group. This is automatically 327called if none was specified during creation of this resent group object. 328 329The content of this field is described in RFC2821 section 4.4. It could use 330some improvement. 331 332=item $obj-E<gt>B<detected>($type, $software, $version) 333 334Inherited, see L<Mail::Message::Head::FieldGroup/"Internals"> 335 336=back 337 338=head2 Error handling 339 340Extends L<"Error handling" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Error handling">. 341 342=over 4 343 344=item $obj-E<gt>B<AUTOLOAD>() 345 346Inherited, see L<Mail::Reporter/"Error handling"> 347 348=item $obj-E<gt>B<addReport>($object) 349 350Inherited, see L<Mail::Reporter/"Error handling"> 351 352=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) 353 354=item Mail::Message::Head::ResentGroup-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) 355 356Inherited, see L<Mail::Reporter/"Error handling"> 357 358=item $obj-E<gt>B<details>() 359 360Inherited, see L<Mail::Message::Head::FieldGroup/"Error handling"> 361 362=item $obj-E<gt>B<errors>() 363 364Inherited, see L<Mail::Reporter/"Error handling"> 365 366=item $obj-E<gt>B<log>( [$level, [$strings]] ) 367 368=item Mail::Message::Head::ResentGroup-E<gt>B<log>( [$level, [$strings]] ) 369 370Inherited, see L<Mail::Reporter/"Error handling"> 371 372=item $obj-E<gt>B<logPriority>($level) 373 374=item Mail::Message::Head::ResentGroup-E<gt>B<logPriority>($level) 375 376Inherited, see L<Mail::Reporter/"Error handling"> 377 378=item $obj-E<gt>B<logSettings>() 379 380Inherited, see L<Mail::Reporter/"Error handling"> 381 382=item $obj-E<gt>B<notImplemented>() 383 384Inherited, see L<Mail::Reporter/"Error handling"> 385 386=item $obj-E<gt>B<print>( [$fh] ) 387 388Inherited, see L<Mail::Message::Head::FieldGroup/"Error handling"> 389 390=item $obj-E<gt>B<report>( [$level] ) 391 392Inherited, see L<Mail::Reporter/"Error handling"> 393 394=item $obj-E<gt>B<reportAll>( [$level] ) 395 396Inherited, see L<Mail::Reporter/"Error handling"> 397 398=item $obj-E<gt>B<trace>( [$level] ) 399 400Inherited, see L<Mail::Reporter/"Error handling"> 401 402=item $obj-E<gt>B<warnings>() 403 404Inherited, see L<Mail::Reporter/"Error handling"> 405 406=back 407 408=head2 Cleanup 409 410Extends L<"Cleanup" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Cleanup">. 411 412=over 4 413 414=item $obj-E<gt>B<DESTROY>() 415 416Inherited, see L<Mail::Reporter/"Cleanup"> 417 418=back 419 420=head1 DIAGNOSTICS 421 422=over 4 423 424=item Error: Message header required for creation of ResentGroup. 425 426It is required to know to which header the resent-group 427is created. Use the C<head> option. Maybe you should use 428L<Mail::Message::Head::Complete::addResentGroup()|Mail::Message::Head::Complete/"Access to the header"> with DATA, which will 429organize the correct initiations for you. 430 431=item Error: Package $package does not implement $method. 432 433Fatal error: the specific package (or one of its superclasses) does not 434implement this method where it should. This message means that some other 435related classes do implement this method however the class at hand does 436not. Probably you should investigate this and probably inform the author 437of the package. 438 439=back 440 441=head1 SEE ALSO 442 443This module is part of Mail-Message distribution version 3.011, 444built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/> 445 446=head1 LICENSE 447 448Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog. 449 450This program is free software; you can redistribute it and/or modify it 451under the same terms as Perl itself. 452See F<http://dev.perl.org/licenses/> 453 454