Liz::TrackSet - Track emails sent with Liz::Mail and Liz::BulkMail
use Liz::TrackSet;
$file = new Liz::TrackSet;
#!/usr/local/bin/perl
use Liz::TrackSet;
The Liz::TrackSet package allows for very simple storage of sets of records related to sending and returning of email.
The Liz::TrackSet module itself works best when incorporated into a client module because it moves the responsibility of aquiring a connection to a database to the client module and it allows any customisation to take place transparently to the developer.
Take for example the TrackSet method of HN.pm module:
sub TrackSet {
# Obtain the parameters # Start the file using the $hn handle as the database handle # Return the finished object
my( $hn,$token ) = @_; my( $trackset ) = Liz::TrackSet->new( $token,$hn ); $trackset; }
Because of the above code in HN.pm, it is now possible to write the following code:
$hn = new HN; $trackset = $hn->TrackSet( 'technology' );
Note that the database connection of the file is hidden in the creation of
the $hn object.
The following methods can be called without an object specification, but as a class method such as Liz::TrackSet->method().
Return list of file identification names of all tracksets in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.
1 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace) 2 wildcard specification to match (default: all)
1 reference to list of identification names in the current database 2 reference to hash with full names
$hn = new HN;
($id,$name) = $hn->TrackSets;
$tracksets = @{$id};
print "All $tracksets tracksets in Hospitality Net:\n";
foreach( @{$id} ) {
print " TrackSet '$$name{$_}' ($_)\n";
}
In HN.pm:
sub TrackSets { Liz::TrackSet->tracksets( @_ ) }
Create a new Liz::TrackSet object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but rather incorporated inside a Client Module.
1 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace) 2 identification name of file set (default: default file set for database)
1 instantiated object 2 flag whether TrackSet was just created
$hn = new HN; $trackset = $hn->TrackSet( 'technology' );
In HN.pm:
sub TrackSet { Liz::TrackSet->new( @_ ) }
Delete all tables of the TrackSet object. Please use this with caution, as it will destroy any information that is stored for this TrackSet. If called in a void context, no tables exist for this TrackSet anymore, and any references in the NextID table are also removed. Otherwise, the tables will be re-created automatically and a new object will be returned, just as if the new method was called.
1 newly created TrackSet object, current object will not work anymore
$trackset->reset;
$trackset = $trackset->reset;
The following methods allow changes to information that is associated with an entire trackset.
Specify or return the non-standard encryption key of the trackset object. The encryption key can be any string. It is used to encrypt tracking information into the email header, so that it is less obvious to receivers what the information actually is.
If there is no encryption key known for the TrackSet, a default encryption key will be used.
1 new encryption key of trackset (default: no change)
1 current/old encryption key of trackset
$xxlink = new xxLINK; $trackset = $xxlink->TrackSet( 'eurest' ); $trackset->EncryptionKey( 'secret' );
Please note that the encryption key used must remain the same for the lifetime of a TrackSet. A change in the EncryptionKey will make all emails sent before the change untrackable.
Specify or return the number of minutes after which a record in the trackset should expire. Records that expire will be removed from the trackset without any further ado.
If there is no expiration time known, a default of one week (7*24*60 = 10080 minutes) will be assumed.
1 new number of minutes to expire after (default: no change)
1 current/old number of minutes to expire after
$xxlink = new xxLINK; $trackset = $xxlink->TrackSet( 'eurest' ); $trackset->ExpireAfter( 14*24*60 );
Specify or return the current name of the trackset object. The name can be anything to further identify the goal of the trackset.
1 new name of trackset (default: no change)
1 current/old name of trackset
$xxlink = new xxLINK; $trackset = $xxlink->TrackSet( 'eurest' ); $trackset->Name( 'Eurestjes' );
The following methods allow changes to a single record in a TrackSet.
Delete a specific Liz::TrackSet::Record object from the database.
1..N identifiers of the Liz::TrackSet::Record to be deleted
1 flag: whether action was successful
$record->delete;
Create a new Liz::TrackSet::Record object, either from existing information or for a new entry. For more documentation, see the Liz::TrackSet::Record object itself.
1 identifying string to create Record object with (default: none = new record)
1 instantiated Record object
$hn = new HN; $trackset = $hn->TrackSet( 'technology' );
$record = $trackset->Record; $record = $trackset->Record( $identifier );
Return an SQL statement handle for a list of records.
The following fields may be specified with the 2nd parameter:
identifier The unique identifier of the record
created Timestamp value when this record was created
updated Timestamp when the record was last updated
expired Timestamp when the record is to be expired
externalID ID to which this record is associated
options Options associated with the record
1 fields to return (comma delimited) (default: 'identifier,created,updated,expired,externalID,options' ); 2 fieldname on which to order the result (default: 'created') 3 extra condition to be applied (default: none)
1 SQL statement handle (on which method "fetchrow" can be applied)
The following methods are associated with the Liz::Mail and Liz::BulkMail packages for sending and receiving mail.
Send an email from a Liz::Mail object, or a whole batch of emails from a Liz::BulkMail object. Add identifying parameters to each email sent, so that returned emails can be tracked and dealt with.
1 Liz::(Bulk)Mail object to send email(s) of
2 options to apply to all TrackSet records made this time
(default: none)
3 method to be executed on the object
(default: 'send')
4..N parameters to be passed to the method
1..N output parameters from Liz::(Bulk)Mail->$method
$trackset->Track( $mail ); $trackset->Track( $bulkmail,'O','sendbg' );
Receive an email either as a Liz::Mail object, or from STDIN. Look for information that would indicate it is a bounced mail, or a reply to a mail previously sent and tracked with this module. Return the identifier of the Liz::TrackSet::Record object to which the mail is associated if possible. Optionally return the Liz::Mail object that was possibly created also.
Can be called as a either a class method or as an object method. When called as a class method, the second input parameter must be specified with the value of the EncryptionKey if a non-standard encryption key was used.
1 email to be processed (as a Liz::Mail object or as text) (default: everything that can be read from STDIN) 2 encryption key to be used (default: Trackset's encryption key, must be specified if called as class method)
1 Liz::Mail object that was possibly created (otherwise same as input parameter) 2 identifier of the Liz::TrackSet::Record object found in subject 3 identifier of the Liz::TrackSet::Record object in header 4 external ID found in identifier 5 Liz::TrackSet token found in identifier 6 client module found in identifier
$client = new Client; $trackset = $client->TrackSet; ($mail,$identifier) = $trackset->receive;
Elizabeth Mattijsen ( lizperl@INC.nl )
(C) 1998-1999 International Network Consultants
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method receive.
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Record.
First version of this true Perl module. Copied from the Liz::EventSet module, which is less specific than this.