view release on metacpan or  search on metacpan

Dbx.pm  view on Meta::CPAN

Fortunately this module gives you the information you need. A common approach would be the following:

    1) create a new Mail::Transport::Dbx object from "Folders.dbx"
    
    2) iterate over its items using the get() method
        2.1 if it returns a Mail::Transport::Dbx::Email  
            => a message
        2.2 if it returns a Mail::Transport::Dbx::Folder 
            => a folder
        
    3) if message
        3.1 call whatever method from Mail::Transport::Dbx::Email 
            you need
        
    4) if folder
        4.1 call whatever method from Mail::Transport::Dbx::Folder 
            you need
        OR
        4.2 call dbx() on it to create a new Mail::Transport::Dbx 
            object
            4.2.1 if dbx() returned something defined
                  => rollback to item 2)

The confusing thing is that .dbx files may contain references to other folders that don't really exist! If Outlook Express was used a newsclient this is a common scenario since Folders.dbx lists B<all> newsgroups as separate C<Mail::Transport::Dbx::F...

=head1 METHODS

The following are methods for B<Mail::Transport::Dbx> objects:

=over

=item B<new(filename)>

=item B<new(filehandle-ref)>

Passed either a string being the filename or an already opened and readable filehandle ref, C<new()> will construct a Mail::Transport::Dbx object from that.

This happens regardless of whether you open an ordinary dbx file or the special F<Folders.dbx> file that contains an overview over all available dbx subfolders.

If opening fails for some reason your program will instantly C<die()> so be sure to wrap the constructor into an C<eval()> and check for C<$@>:

    my $dbx = eval { Mail::Transport::Dbx->new( "file.dbx" ) };
    die $@ if $@;

Be careful with using a filehandle, though. On Windows, you might need to use C<binmode()> on your handle or otherwise the stream from your dbx file might get corrupted.

=item B<msgcount>

Returns the number of items stored in the dbx structure. If you previously opened Folders.dbx C<msgcount()> returns the number of subfolders in it. Otherwise it returns the number of messages. C<msgcount() - 1> is the index of the last item.

=item B<emails>

In list context this method returns all emails contained in the file. In boolean (that is, scalar) context it returns a true value if the file contains emails and false if it contains subfolders.

    if ($dbx->emails) {
        print "I contain emails";
    } else {
        print "I contain subfolders";
    }

This is useful for iterations:

    for my $msg ($dbx->emails) {
        ...
    }

=item B<subfolders>

In list context this method returns all subfolders of the current file as C<Mail::Transport::Dbx::Folder> objects. In boolean (scalar) context it returns true of the file contains subfolders and false if it contains emails.

Remember that you still have to call C<dbx()> on these subfolders if you want to do something useful with them:

    for my $sub ($dbx->subfolders) {
        if (my $d = $sub->dbx) {
            # $d now a proper Mail::Transport::Dbx object 
            # with content
        } else {
            print "Subfolder referenced but non-existent";
        }
    }

=item B<get(n)>

Get the item at the n-th position. First item is at position 0. C<get()> is actually a factory method so it either returns a C<Mail::Transport::Dbx::Email> or C<Mail::Transport::Dbx::Folder> object. This depends on the folder you call this method upo...

    my $dbx  = Mail::Transport::Dbx->new( "Folders.dbx" );
    my $item = $dbx->get(0);

C<$item> will now definitely be a C<Mail::Transport::Dbx::Folder> object since F<Folders.dbx> doesn't contain emails but references to subfolders.

You can use the C<is_email()> and C<is_folder()> method to check for its type:

    if ($item->is_email) {
        print $item->subject;
    } else {
        # it's a subfolder
        ...
    }

On an error, this method returns an undefined value. Check C<$dbx-E<gt>errstr> to find out what went wrong.

=item B<errstr>

Whenever an error occurs, C<errstr()> will contain a string giving you further help what went wrong. 

B<WARNING:> Internally it relies on a global variable so all objects will have the same error-string! That means it only makes sense to use it after an operation that potentially raises an error:

    # example 1
    my $dbx = Mail::Transport::Dbx->new("box.dbx")
        or die Mail::Transport::Dbx->errstr;

    # example 2
    my $msg = $dbx->get(5) or print $dbx->errstr;

=item B<error>

Similar to C<errstr()>, only that it will return an error code. See "Exportable constants/Error-Codes" under L<"EXPORT"> for codes that can be returned.

=back

The following are the methods for B<Mail::Transport::Dbx::Email> objects: