/ 
Sendmail-Queue-0.800
River stage zero No dependents
/ Sendmail::Queue::Qf

NAME

Sendmail::Queue::Qf - Represent a Sendmail qfXXXXXXXX (control) file

SYNOPSIS

    use Sendmail::Queue::Qf;

    # Create a new qf file object
    my $qf = Sendmail::Queue::Qf->new({
	queue_directory => $dir
    });

    # Creates a new qf file, locked.
    $qf->create_and_lock();

    $qf->set_sender('me@example.com');
    $qf->add_recipient('you@example.org');

    $qf->set_headers( $some_header_data );

    # Add a received header using the information already provided
    $qf->synthesize_received_header();

    $qf->write( );

    $qf->sync();

    $qf->close();

DESCRIPTION

Sendmail::Queue::Qf provides a representation of a Sendmail qf file.

METHODS

new ( \%args )

Create a new Sendmail::Queue::Qf object.

create_and_lock ( [$lock_both] )

Generate a Sendmail 8.12-compatible queue ID, and create a locked qf file with that name. If $lock_both is true, we lock the file using both fcntl and flock-style locking.

See Bat Book 3rd edition, section 11.2.1 for information on how the queue file name is generated.

Note that we create the qf file directly, rather than creating an intermediate tf file and renaming aftewards. This is all good and well for creating /new/ qf files -- sendmail does it that way as well -- but if we ever want to rewrite one, it's not safe.

For future reference, Sendmail queuefile creation in queueup() inside sendmail/queue.c does things in the same way -- newly-created queue files are created directly with the qf prefix, then locked, then written.

synthesize_received_header ( )

Create a properly-formatted Received: header for this message, using any data available from the object.

The generated header is saved internally as 'received_header'.

get_queue_filename

Return the full path name of this queue file.

Will return undef if no queue ID exists, and die if queue directory is unset.

add_recipient ( $recipient [, $recipient, $recipient ] )

Add one or more recipients to this object.

write ( )

Writes a qfXXXXXXX file using the object's data.

A path to create this queue file under must be provided, by first calling ->set_queue_directory()

sync ( )

Force any data written to the current filehandle to be flushed to disk. Returns 1 on success, undef if no queue file is open, and will die on error.

close ( )

Returns true on success, false (as undef) if filehandle wasn't open, or if closing the filehandle fails, and dies if the internal filehandle is missing or isn't a filehandle.

clone ( )

Return a clone of this Sendmail::Queue::Qf object, containing everything EXCEPT:

  • recipients

  • queue ID

  • open queue filehandle

  • synthesized Received: header

Unlink the queue file. Returns true (1) on success, false (undef) on failure.

Unlinking the queue file will only succeed if:

  • we have a queue directory and queue ID configured for this object

  • the queue file is open and locked

Otherwise, we fail to delete.

DEPENDENCIES

Core Perl Modules

Carp, File::Spec, Scalar::Util, Time::Local, Fcntl, Errno

Other Modules

Mail::Header::Generator

INCOMPATIBILITIES

There are no known incompatibilities with this module.

BUGS AND LIMITATIONS

There are no known bugs in this module. Please report problems to the author. Patches are welcome.

AUTHOR

Dave O'Neill, <support at roaringpenguin.com>

LICENCE AND COPYRIGHT

Copyright (c) 2007 Roaring Penguin Software, Inc. All rights reserved.