Dbx(3) User Contributed Perl Documentation Dbx(3)NAMEMail::Transport::Dbx - Parse Outlook Express mailboxes
SYNOPSIS
use Mail::Transport::Dbx;
my $dbx = eval { Mail::Transport::Dbx->new("box.mbx") };
die $@ if $@;
for my $i (0 .. $dbx->msgcount - 1) {
my $msg = $dbx->get($i);
print $msg->subject;
...
}
# more convenient
for my $msg ($dbx->emails) {
print $msg->subject;
...
}
ABSTRACT
Read dbx files (mailbox files of Outlook Express)
DESCRIPTIONMail::Transport::Dbx gives you platform independent access to Outlook
Express' dbx files. Extract subfolders, messages etc. from those or
use it to convert dbx archives into a more portable format (such as
standard mbox format).
It relies on LibDBX to do its job. The bad news: LibDBX knows nothing
about the endianness of your machine so it does not work on big-endian
machines such as Macintoshs or SUNs. The good news: I made the
appropriate patches so that it in fact does work even on machines with
the 'wrong' byteorder (exception: machines with an even odder byteorder
such as Crays are not suppored; exception from the exception: If you
buy me a Cray I'll promise to fix it. :-).
You have to understand the structure of .dbx files to make proper use
of this module. Outlook Express keeps a couple of those files on your
harddisk. For instance:
Folders.dbx
folder1.dbx
comp.lang.perl.misc.dbx
The nasty thing about that is that there are really two different kinds
of such files: One that contains the actual messages and one that
merely holds references to other .dbx files. Folders.dbx could be
considered the toplevel file since it lists all other available .dbx
files. As for folder1.dbx and comp.lang.perl.misc.dbx you can't yet
know whether they contain messages or subfolders (though
comp.lang.perl.misc.dbx probably contains newsgroup messages that are
treated as mere emails).
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 all
newsgroups as separate "Mail::Transport::Dbx::Folder" objects no matter
whether you are subscribed to any of those or not. So in essence
calling "dbx()" on a folder will only return a new object if the
corresponding .dbx file exists.
METHODS
The following are methods for Mail::Transport::Dbx objects:
new(filename)
new(filehandle-ref)
Passed either a string being the filename or an already opened and
readable filehandle ref, "new()" will construct a
Mail::Transport::Dbx object from that.
This happens regardless of whether you open an ordinary dbx file or
the special Folders.dbx file that contains an overview over all
available dbx subfolders.
If opening fails for some reason your program will instantly
"die()" so be sure to wrap the constructor into an "eval()" and
check for $@:
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 "binmode()" on your handle or otherwise the stream from
your dbx file might get corrupted.
msgcount
Returns the number of items stored in the dbx structure. If you
previously opened Folders.dbx "msgcount()" returns the number of
subfolders in it. Otherwise it returns the number of messages.
"msgcount() - 1" is the index of the last item.
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) {
...
}
subfolders
In list context this method returns all subfolders of the current
file as "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 "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";
}
}
get(n)
Get the item at the n-th position. First item is at position 0.
"get()" is actually a factory method so it either returns a
"Mail::Transport::Dbx::Email" or "Mail::Transport::Dbx::Folder"
object. This depends on the folder you call this method upon:
my $dbx = Mail::Transport::Dbx->new( "Folders.dbx" );
my $item = $dbx->get(0);
$item will now definitely be a "Mail::Transport::Dbx::Folder"
object since Folders.dbx doesn't contain emails but references to
subfolders.
You can use the "is_email()" and "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
"$dbx->errstr" to find out what went wrong.
errstr
Whenever an error occurs, "errstr()" will contain a string giving
you further help what went wrong.
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;
error
Similar to "errstr()", only that it will return an error code. See
"Exportable constants/Error-Codes" under "EXPORT" for codes that
can be returned.
The following are the methods for Mail::Transport::Dbx::Email objects:
as_string
Returns the whole message (header and body) as one large string.
Note that the string still contains the raw newlines as used by
DOSish systems (\015\012). If you want newlines to be represented
in the native format of your operating system, use the following:
my $email = $msg->as_string;
$email =~ s/\015\012/\n/g;
On Windows this is a no-op so you can ommit this step.
Especially for news-articles this method may return "undef". This
always happens when the particular articles was only partially
downloaded (that is, only header retrieved from the newsserver).
There is no way to retrieve this header literally with "header".
Methods like "subject" etc. however do work.
header
Returns the header-portion of the whole email.
With respect to newlines the same as described under "as_string()"
applies.
Returns "undef" under the same circumstances as "as_string".
body
Returns the body-portion of the whole email.
With respect to newlines the same as described under "as_string()"
applies.
Returns "undef" under the same circumstances as "as_string".
subject
Returns the subject of the email as a string.
psubject
Returns the processed subject of the email as a string. 'Processed'
means that additions such as "Re:" etc. are cut off.
msgid
Returns the message-id of the message as a string.
parents_ids
Returns the message-ids of the parent messages as a string.
sender_name
Returns the name of the sender of this email as a string.
sender_address
Returns the address of the sender of this email as a string.
recip_name
Returns the name of the recipient of this email as a string. This
might be your name. ;-)
recip_address
Returns the address of the recipient of this email as a string.
oe_account_name
Returns the Outlook Express account name this message was retrieved
with as a string.
oe_account_num
Outlook Express accounts also seem to have a numerical
representation. This method will return this as a string (something
like "0000001").
fetched_server
Returns the name of the POP server that this message was retrieved
from as a string.
rcvd_localtime
This is the exact duplicate of Perl's builtin "localtime()" applied
to the date this message was received. It returns a string in
scalar context and a list with nine elements in list context. See
'perldoc -f localtime' for details.
rcvd_gmtime
Same as "rcvd_localtime()" but returning a date conforming to GMT.
date_received( [format, [len, [gmtime]]] )
This method returns the date this message was received by you as a
string. The date returned is calculated according to "localtime()".
Without additional arguments, the string returned looks something
like
Sun Apr 14 02:27:57 2002
The optional first argument is a string describing the format of
the date line. It is passed unchanged to strftime(3). Please
consult your system's documentation for strftime(3) to see how such
a string has to look like. The default string to render the date is
"%a %b %e %H:%M:%S %Y".
The optional second argument is the max string length to be
returned by "date_received()". This parameter is also passed
unaltered to "strftime()". This method uses 25 as default
The third argument can be set to a true value if you rather want to
get a date in GMT. So if you want to get the GMT of the date but
want to use the default rendering settings, you will have to
provide them yourself:
print $msg->date_received("%a %b %e %H:%M:%S %Y", 25, 1);
is_seen
Returns a true value if this message has already been seen. False
otherwise.
is_email
Always returns true for this kind of object.
is_folder
Always returns false for this kind of object.
The following methods exist for Mail::Transport::Dbx::Folder objects:
dbx This is a convenience method. It creates a "Mail::Transport::Dbx"
object from the folder object. If the folder is only mentioned but
not physically existing on your hard-drive (either because you
deleted the .dbx file or it was actually never there which
especially happens for newsgroup files) "dbx" returns an undefined
value.
Please read "DESCRIPTION" again to learn why "dbx()" can return an
undefined value.
num The index number of this folder. This is the number you passed to
"$dbx->get()" to retrieve this folder.
type
According to libdbx.h this returns one of "DBX_TYPE_FOLDER" or
"DBX_TYPE_EMAIL". Use it to check whether the folder contains
emails or other folders.
name
The name of the folder.
file
The filename of the folder. Use this, to create a new
"Mail::Transport::Dbx" object:
# $folder is a Mail::Transport::Dbx::Folder object
my $new_dbx = Mail::Transport::Dbx->new( $folder->file );
Consider using the "dbx()" method instead.
This method returns an undefined value if there is no .dbx file
belonging to this folder.
id Numerical id of the folder. Not sure what this is useful for.
parent_id
Numerical id of the parent's folder.
folder_path
Returns the full folder name of this folder as a list of path
elements. It's then in your responsibility to join them together by
using a delimiter that doesn't show up in any of the elements. ;-)
print join("/", $_->folder_path), "\n" for $dbx->subfolders;
# could for instance produce a long list, such as:
Outlook Express/news.rwth-aachen.de/de.comp.software.announce
Outlook Express/news.rwth-aachen.de/de.comp.software.misc
...
Outlook Express/Lokale Ordner/test/test1
Outlook Express/Lokale Ordner/test
Outlook Express/Lokale Ordner/Entwuerfe
Outlook Express/Lokale Ordner/Geloeschte Objekte
Outlook Express/Lokale Ordner/Gesendete Objekte
Outlook Express/Lokale Ordner/Postausgang
Outlook Express/Lokale Ordner/Posteingang
Outlook Express/Lokale Ordner
Outlook Express/Outlook Express
Note that a slash (as any other character) might not be a safe
choice as it could show up in a folder name.
EXPORT
None by default.
Exportable constants
If you intend to use any of the following constants, you have to import
them when "use()"ing the module. You can import them all in one go
thusly:
use Mail::Transport::Dbx qw(:all);
Or you import only those you need:
use Mail::Transport::Dbx qw(DBX_TYPE_EMAIL DBX_TYPE_FOLDER);
Error-Codes
· DBX_NOERROR
No error occured.
· DBX_BADFILE
Dbx file operation failed (open or close)
· DBX_DATA_READ
Reading of data from dbx file failed
· DBX_INDEXCOUNT
Index out of range
· DBX_INDEX_OVERREAD
Request was made for index reference greater than exists
· DBX_INDEX_UNDERREAD
Number of indexes read from dbx file is less than expected
· DBX_INDEX_READ
Reading of Index Pointer from dbx file failed
· DBX_ITEMCOUNT
Reading of Item Count from dbx file failed
· DBX_NEWS_ITEM
Item is a news item not an email
Dbx types
One of these is returned by "$folder->type" so you can check
whether the folder contains emails or subfolders. Note that only
DBX_TYPE_EMAIL and DBX_TYPE_FOLDER are ever returned so even
newsgroup postings are of the type DBX_TYPE_EMAIL.
· DBX_TYPE_EMAIL
· DBX_TYPE_FOLDER
· DBX_TYPE_NEWS
Don't use this one!
· DBX_TYPE_VOID
I have no idea what this is for.
Miscellaneous constants
· DBX_EMAIL_FLAG_ISSEEN
· DBX_FLAG_BODY
CAVEATS
You can't retrieve the internal state of the objects using
"Data::Dumper" or so since "Mail::Transport::Dbx" uses a blessed scalar
to hold a reference to the respective C structures. That means you have
to use the provided methods for each object. Call that strong
encapsultion if you need an euphemism for that.
There are currently no plans to implement write access to .dbx files. I
leave that up to the authors of libdbx.
KNOWN BUGS
Other than that I don't know yet of any. This, of course, has never
actually been a strong indication for the absence of bugs.
SEE ALSO
http://sourceforge.net/projects/ol2mbox hosts the libdbx package. It
contains the library backing this module along with a description of
the file format for .dbx files.
AUTHOR
Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>
COPYRIGHT AND LICENSE
Copyright 2003-2005 by Tassilo von Parseval
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2005-06-23 Dbx(3)
