NAME

Palm::Treo680MessagesDB - Handler for Treo 680 SMS message databases

SYNOPSIS

use Palm::PDB;
use Palm::Treo680MessagesDB timezone => 'Europe/London';
use Data::Dumper;

my $pdb = Palm::PDB->new();
$pdb->Load("MessagesDB.pdb");
print Dumper(@{$pdb->{records}});

DESCRIPTION

This is a helper class for the Palm::PDB package, which parses the database generated by a Treo 680 as a record of all your SMSes.

OPTIONS

You can set some global options when you 'use' the module:

timezone

Defaults to 'Europe/London'.

incl_raw

Whether to include the raw binary blob of data in the parsed records. Defaults to false.

debug

Defaults to false.

If false, unknown record-types and those which look like they weren't parsed properly (eg they have an impossible timestamp) are suppressed. This is done by over-riding Palm::PDB's Load() method.

If true, include a hexadecimal dump of each record in the 'debug' field, and don't suppress unknown or badly parsed records.

METHODS

This class inherits from Palm::Raw, so has all of its methods. The folliwing are over-ridden, and differ from that in the parent class thus:

ParseRecord

Returns data structures with the following keys:

rawdata

The raw data blob passed to the method. This is only present if the incl_raw option is true.

date

The date of the message, if available, in YYYY-MM-DD format

time

The time of the message, if available, in HH:MM format

epoch or timestamp (it's available under both names)

The epoch time of the message, if available. Note that because the database doesn't store the timezone, we assume 'Europe/London' when converting this to the seperate date and time fields. If you want to change that, then suppy a timezone option when you 'use' the module.

Note that this is always the Unix epoch time, even though PalmOS uses an epoch based on 1904.

name

The name of the other party, which the Treo extracts from the SIM phone-book or from the Palm address book at the time the SMS is saved.

number or phone

The number of the other party. This is not normalised so you might see the same number in different formats, eg 07979866975 and +447979866975. I may add number normalisation in the future.

direction

Either 'incoming', or 'outgoing'.

Other fields may be added in the future.

BUGS, LIMITATIONS and FEEDBACK

The database structure is undocumented. Consequently it has had to be reverse-engineered. There appear to be several message formats in the database. Some have a superficial resemblance to those used by the 650 (and which is partially documented by Palm) but there is no publicly available documentation that I could find for the others - if you know where I can get docs, please let me know!

I can only reverse-engineer record formats that appear on my phone, so there may be some missing. In addition, I may decode some formats incorrectly because they're not quite what I thought they were. If this affects you, please please please send me the offending data.

There is currently no support for creating a new database, or for editing the contents of an existing database. If you need that functionality, please submit a patch with tests. I will *not* write this myself unless I need it. Behaviour if you try to create or edit a database is currently undefined, but editing a database will almost certainly break it.

If you find any bugs please report them either using http://rt.cpan.org/ or by email. Ideally, I would like to receive sample data and a test file, which fails with the latest version of the module but will pass when I fix the bug.

Sample data can be either in the form of a complete database, or a dump of just a single record structure, which *must* include the raw binary data - use the 'incl_raw' option when you load the module, and save the data structure to a file using Data::Dumper. Feel free to obscure real names, phone numbers, and messages in the data, but you should ensure that phone numbers are correctly formed, and that you don't change the length of any parts of the message. Also, please don't change any non-human-readable parts of the record.

SEE ALSO

Palm::SMS, which handles SMS messages databases on some other models of Treo.

Palm::PDB

DateTime

THANKS TO

Michal Seliga, for sample MMS data

AUTHOR, COPYRIGHT and LICENCE

Copyright 2008 David Cantrell <david@cantrell.org.uk>

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

This module is also free-as-in-mason software.