—
—
—
—

              
# Palm::Address.pm
# 
# Perl class for dealing with Palm AddressBook databases. 
#
#       Copyright (C) 1999, 2000, Andrew Arensburger.
#       You may distribute this file under the terms of the Artistic
#       License, as specified in the README file.
use strict;
package Palm::Address;
use Palm::Raw();
use Palm::StdAppInfo();
use vars qw( $VERSION @ISA
        $numFieldLabels $addrLabelLength @phoneLabels @countries
        %fieldMapBits );
# One liner, to allow MakeMaker to work.
$VERSION = '1.011_01';
@ISA = qw( Palm::StdAppInfo Palm::Raw );
# AddressDB records are quite flexible and customizable, and therefore
# a pain in the ass to deal with correctly.
HideShow 127 lines of Pod
=head1 NAME
Palm::Address - Handler for Palm AddressBook databases
=head1 SYNOPSIS
    use Palm::Address;
=head1 DESCRIPTION
The Address PDB handler is a helper class for the Palm::PDB package.
It parses AddressBook databases.
=head2 AppInfo block
The AppInfo block begins with standard category support. See
L<Palm::StdAppInfo> for details.
Other fields include:
    $pdb->{appinfo}{lastUniqueID}
    $pdb->{appinfo}{dirtyFields}
I don't know what these are.
    $pdb->{appinfo}{fieldLabels}{name}
    $pdb->{appinfo}{fieldLabels}{firstName}
    $pdb->{appinfo}{fieldLabels}{company}
    $pdb->{appinfo}{fieldLabels}{phone1}
    $pdb->{appinfo}{fieldLabels}{phone2}
    $pdb->{appinfo}{fieldLabels}{phone3}
    $pdb->{appinfo}{fieldLabels}{phone4}
    $pdb->{appinfo}{fieldLabels}{phone5}
    $pdb->{appinfo}{fieldLabels}{phone6}
    $pdb->{appinfo}{fieldLabels}{phone7}
    $pdb->{appinfo}{fieldLabels}{phone8}
    $pdb->{appinfo}{fieldLabels}{address}
    $pdb->{appinfo}{fieldLabels}{city}
    $pdb->{appinfo}{fieldLabels}{state}
    $pdb->{appinfo}{fieldLabels}{zipCode}
    $pdb->{appinfo}{fieldLabels}{country}
    $pdb->{appinfo}{fieldLabels}{title}
    $pdb->{appinfo}{fieldLabels}{custom1}
    $pdb->{appinfo}{fieldLabels}{custom2}
    $pdb->{appinfo}{fieldLabels}{custom3}
    $pdb->{appinfo}{fieldLabels}{custom4}
    $pdb->{appinfo}{fieldLabels}{note}
These are the names of the various fields in the address record.
    $pdb->{appinfo}{country}
An integer: the code for the country for which these labels were
designed. The country name is available as
        $Palm::Address::countries[$pdb->{appinfo}{country}];
    $pdb->{appinfo}{misc}
An integer. The least-significant bit is a flag that indicates whether
the database should be sorted by company. The other bits are reserved.
=head2 Sort block
    $pdb->{sort}
This is a scalar, the raw data of the sort block.
=head2 Records
    $record = $pdb->{records}[N];
    $record->{fields}{name}
    $record->{fields}{firstName}
    $record->{fields}{company}
    $record->{fields}{phone1}
    $record->{fields}{phone2}
    $record->{fields}{phone3}
    $record->{fields}{phone4}
    $record->{fields}{phone5}
    $record->{fields}{address}
    $record->{fields}{city}
    $record->{fields}{state}
    $record->{fields}{zipCode}
    $record->{fields}{country}
    $record->{fields}{title}
    $record->{fields}{custom1}
    $record->{fields}{custom2}
    $record->{fields}{custom3}
    $record->{fields}{custom4}
    $record->{fields}{note}
These are scalars, the values of the various address book fields.
    $record->{phoneLabel}{phone1}
    $record->{phoneLabel}{phone2}
    $record->{phoneLabel}{phone3}
    $record->{phoneLabel}{phone4}
    $record->{phoneLabel}{phone5}
Most fields in an AddressBook record are straightforward: the "name"
field always gives the person's last name.
The "phoneI<N>" fields, on the other hand, can mean different things
in different records. There are five such fields in each record, each
of which can take on one of eight different values: "Work", "Home",
"Fax", "Other", "E-mail", "Main", "Pager" and "Mobile".
The $record->{phoneLabel}{phone*} fields are integers. Each one is
an index into @Palm::Address::phoneLabels, and indicates which
particular type of phone number each of the $record->{phone*} fields
represents.
    $record->{phoneLabel}{display}
Like the phone* fields above, this is an index into
@Palm::Address::phoneLabels. It indicates which of the phone*
fields to display in the list view.
    $record->{phoneLabel}{reserved}
I don't know what this is.
=head1 METHODS
=cut
#'
$addrLabelLength = 16;
$numFieldLabels = 22;
@phoneLabels = (
        "Work",
        "Home",
        "Fax",
        "Other",
        "E-mail",
        "Main",
        "Pager",
        "Mobile",
        );
@countries = (
        "Australia",
        "Austria",
        "Belgium",
        "Brazil",
        "Canada",
        "Denmark",
        "Finland",
        "France",
        "Germany",
        "Hong Kong",
        "Iceland",
        "Ireland",
        "Italy",
        "Japan",
        "Luxembourg",
        "Mexico",
        "Netherlands",
        "New Zealand",
        "Norway",
        "Spain",
        "Sweden",
        "Switzerland",
        "United Kingdom",
        "United States",
);
# fieldMapBits
# Each Address record contains a flag record ($fieldMap, in
# &PackRecord) that indicates which fields exist in the record. This
# hash defines these flags' values.
%fieldMapBits = (
        name            => 0x0001,
        firstName       => 0x0002,
        company         => 0x0004,
        phone1          => 0x0008,
        phone2          => 0x0010,
        phone3          => 0x0020,
        phone4          => 0x0040,
        phone5          => 0x0080,
        address         => 0x0100,
        city            => 0x0200,
        state           => 0x0400,
        zipCode         => 0x0800,
        country         => 0x1000,
        title           => 0x2000,
        custom1         => 0x4000,
        custom2         => 0x8000,
        custom3         => 0x10000,
        custom4         => 0x20000,
        note            => 0x40000,
);
sub import
{
        &Palm::PDB::RegisterPDBHandlers(__PACKAGE__,
                [ "addr", "DATA" ],
                );
}
HideShow 11 lines of Pod
=head2 new
  $pdb = new Palm::Address;
Create a new PDB, initialized with the various Palm::Address fields
and an empty record list.
Use this method if you're creating an Address PDB from scratch.
=cut
#'
# new
# Create a new Palm::Address database, and return it
sub new
{
        my $classname   = shift;
        my $self        = $classname->SUPER::new(@_);
                        # Create a generic PDB. No need to rebless it,
                        # though.
        $self->{name} = "AddressDB"; # Default
        $self->{creator} = "addr";
        $self->{type} = "DATA";
        $self->{attributes}{resource} = 0;
                                # The PDB is not a resource database by
                                # default, but it's worth emphasizing,
                                # since AddressDB is explicitly not a PRC.
        # Initialize the AppInfo block
        $self->{appinfo} = {
                fieldLabels     => {
                        # Displayed labels for the various fields in
                        # each address record.
                        # XXX - These are American English defaults. It'd
                        # be way keen to allow i18n.
                        name            => "Name",
                        firstName       => "First name",
                        company         => "Company",
                        phone1          => "Work",
                        phone2          => "Home",
                        phone3          => "Fax",
                        phone4          => "Other",
                        phone5          => "E-mail",
                        phone6          => "Main",
                        phone7          => "Pager",
                        phone8          => "Mobile",
                        address         => "Address",
                        city            => "City",
                        state           => "State",
                        zipCode         => "Zip Code",
                        country         => "Country",
                        title           => "Title",
                        custom1         => "Custom 1",
                        custom2         => "Custom 2",
                        custom3         => "Custom 3",
                        custom4         => "Custom 4",
                        note            => "Note",
                },
                # XXX - The country code corresponds to "United
                # States". Again, it'd be keen to allow the user's #
                # country-specific defaults.
                country         => 22,
                misc            => 0,
        };
        # Add the standard AppInfo block stuff
        &Palm::StdAppInfo::seed_StdAppInfo($self->{appinfo});
        # Give the PDB a blank sort block
        $self->{sort} = undef;
        # Give the PDB an empty list of records
        $self->{records} = [];
        return $self;
}
HideShow 12 lines of Pod
=head2 new_Record
  $record = $pdb->new_Record;
Creates a new Address record, with blank values for all of the fields.
The AppInfo block will contain only an "Unfiled" category, with ID 0.
C<new_Record> does B<not> add the new record to C<$pdb>. For that,
you want C<$pdb-E<gt>append_Record>.
=cut
# new_Record
# Create a new, initialized record.
sub new_Record
{
        my $classname = shift;
        my $retval = $classname->SUPER::new_Record(@_);
        # Initialize the fields. This isn't particularly enlightening,
        # but every AddressDB record has these.
        $retval->{fields} = {
                name            => undef,
                firstName       => undef, 
                company         => undef,
                phone1          => undef,
                phone2          => undef,
                phone3          => undef,
                phone4          => undef,
                phone5          => undef,
                address         => undef,
                city            => undef,
                state           => undef,
                zipCode         => undef,
                country         => undef,
                title           => undef,
                custom1         => undef,
                custom2         => undef,
                custom3         => undef,
                custom4         => undef,
                note            => undef,
        };
        # Initialize the phone labels
        $retval->{phoneLabel} = {
                phone1  => 0,                # Work
                phone2  => 1,                # Home
                phone3  => 2,                # Fax
                phone4  => 3,                # Other
                phone5  => 4,                # E-mail
                display => 0,                # Display work phone by default
                reserved => undef    # ???
        };
        return $retval;
}
# ParseAppInfoBlock
# Parse the AppInfo block for Address databases.
#
# The AppInfo block has the following overall structure:
#       1: Categories (see StdAppInfo.pm)
#       2: reserved word
#       3: dirty field labels
#       4: field labels
#       5: country
#       6: misc
# 3: I think this is similar to the first part of the standard AppInfo
#    blocka, a bit field of which field labels have changed (i.e.,
#    which fields have been renamed).
# 4: An array of field labels (16-character strings, NUL-terminated).
# 5: The code for the country for which the labels were designed.
# 6: 7 reserved bits followed by one flag that's set if the database
#    should be sorted by company.
sub ParseAppInfoBlock
{
        my $self = shift;
        my $data = shift;
        my $dirtyFields;
        my @fieldLabels;
        my $country;
        my $misc;
        my $i;
        my $appinfo = {};
        my $std_len;
        # Get the standard parts of the AppInfo block
        $std_len = &Palm::StdAppInfo::parse_StdAppInfo($appinfo, $data);
        $data = $appinfo->{other};           # Look at the non-standard part
        # Get the rest of the AppInfo block
        my $unpackstr =         # Argument to unpack()
                "x2" .          # Reserved
                "N" .           # Dirty flags
                "a$addrLabelLength" x $numFieldLabels .
                                # Address labels
                "C" .           # Country
                "C";            # Misc
        ($dirtyFields,
         @fieldLabels[0..($numFieldLabels-1)],
         $country,
         $misc) =
                unpack $unpackstr, $data;
        for (@fieldLabels)
        {
                s/\0.*$//;      # Trim everything after the first NUL
                                # (when renaming custom fields, might
                                # have something like "Foo\0om 1"
        }
        $appinfo->{dirtyFields} = $dirtyFields;
        $appinfo->{fieldLabels} = {
                name            => $fieldLabels[0],
                firstName       => $fieldLabels[1],
                company         => $fieldLabels[2],
                phone1          => $fieldLabels[3],
                phone2          => $fieldLabels[4],
                phone3          => $fieldLabels[5],
                phone4          => $fieldLabels[6],
                phone5          => $fieldLabels[7],
                address         => $fieldLabels[8],
                city            => $fieldLabels[9],
                state           => $fieldLabels[10],
                zipCode         => $fieldLabels[11],
                country         => $fieldLabels[12],
                title           => $fieldLabels[13],
                custom1         => $fieldLabels[14],
                custom2         => $fieldLabels[15],
                custom3         => $fieldLabels[16],
                custom4         => $fieldLabels[17],
                note            => $fieldLabels[18],
                phone6          => $fieldLabels[19],
                phone7          => $fieldLabels[20],
                phone8          => $fieldLabels[21],
                };
        $appinfo->{country} = $country;
        $appinfo->{misc} = $misc;    # XXX - Parse the "misc" field further
        return $appinfo;
}
sub PackAppInfoBlock
{
        my $self = shift;
        my $retval;
        my $i;
        my $other;              # Non-standard AppInfo stuff
        # Pack the application-specific part of the AppInfo block
        $other = pack("x2 N", $self->{appinfo}{dirtyFields});
        $other .= pack("a$addrLabelLength" x $numFieldLabels,
                $self->{appinfo}{fieldLabels}{name},
                $self->{appinfo}{fieldLabels}{firstName},
                $self->{appinfo}{fieldLabels}{company},
                $self->{appinfo}{fieldLabels}{phone1},
                $self->{appinfo}{fieldLabels}{phone2},
                $self->{appinfo}{fieldLabels}{phone3},
                $self->{appinfo}{fieldLabels}{phone4},
                $self->{appinfo}{fieldLabels}{phone5},
                $self->{appinfo}{fieldLabels}{address},
                $self->{appinfo}{fieldLabels}{city},
                $self->{appinfo}{fieldLabels}{state},
                $self->{appinfo}{fieldLabels}{zipCode},
                $self->{appinfo}{fieldLabels}{country},
                $self->{appinfo}{fieldLabels}{title},
                $self->{appinfo}{fieldLabels}{custom1},
                $self->{appinfo}{fieldLabels}{custom2},
                $self->{appinfo}{fieldLabels}{custom3},
                $self->{appinfo}{fieldLabels}{custom4},
                $self->{appinfo}{fieldLabels}{note},
                $self->{appinfo}{fieldLabels}{phone6},
                $self->{appinfo}{fieldLabels}{phone7},
                $self->{appinfo}{fieldLabels}{phone8});
        $other .= pack("C C x2",
                $self->{appinfo}{country},
                $self->{appinfo}{misc});
        $self->{appinfo}{other} = $other;
        # Pack the standard part of the AppInfo block
        $retval = &Palm::StdAppInfo::pack_StdAppInfo($self->{appinfo});
        return $retval;
}
# ParseRecord
# Parse an Address Book record.
# Address book records have the following overall structure:
#       1: phone labels
#       2: field map
#       3: fields
# Each record can contain a number of fields, such as "name",
# "address", "city", "company", and so forth. Each field has an
# internal name ("zipCode"), a printable name ("Zip Code"), and a
# value ("90210").
#
# For most fields, there is a hard mapping between internal and
# printed names: "name" always corresponds to "Last Name". The fields
# "phone1" through "phone5" are different: each of these can be mapped
# to one of several printed names: "Work", "Home", "Fax", "Other",
# "E-Mail", "Main", "Pager" or "Mobile". Multiple internal names can
# map to the same printed name (a person might have several e-mail
# addresses), and the mapping is part of the record (i.e., each record
# has its own mapping).
#
# Part (3) is simply a series of NUL-terminated strings, giving the
# values of the various fields in the record, in a certain order. If a
# record does not have a given field, there is no string corresponding
# to it in this part.
#
# Part (2) is a bit field that specifies which fields the record
# contains.
#
# Part (1) determines the phone mapping described above. This is
# implemented as an unsigned long, but what we're interested in are
# the six least-significant nybbles. They are:
#       disp    phone5  phone4  phone3  phone2  phone1
# ("phone1" is the least-significant nybble). Each nybble holds a
# value in the range 0-15 which in turn specifies the printed name for
# that particular internal name.
sub ParseRecord
{
        my $self = shift;
        my %record = @_;
        delete $record{offset}; # This is useless
        my $phoneFlags;
        my @phoneTypes;
        my $dispPhone;          # Which phone to display in the phone list
        my $reserved;           # Not sure what this is. It's the 8 high bits
                                # of the "phone types" field.
        my $fieldMap;
        my $companyFieldOff;    # Company field offset: offset into the
                                # raw "fields" string of the beginning of
                                # the company name, plus 1. Presumably this
                                # is to allow the address book app to quickly
                                # display by company name. It is 0 in entries
                                # that don't have a "Company" field.
                                # This can be ignored when reading, and
                                # must be computed when writing.
        my $fields;
        my @fields;
        ($phoneFlags, $fieldMap, $companyFieldOff, $fields) =
                unpack("N N C a*", $record{data});
        @fields = split /\0/, $fields;
        # Parse the phone flags
        $phoneTypes[0] =  $phoneFlags        & 0x0f;
        $phoneTypes[1] = ($phoneFlags >>  4) & 0x0f;
        $phoneTypes[2] = ($phoneFlags >>  8) & 0x0f;
        $phoneTypes[3] = ($phoneFlags >> 12) & 0x0f;
        $phoneTypes[4] = ($phoneFlags >> 16) & 0x0f;
        $dispPhone     = ($phoneFlags >> 20) & 0x0f;
        $reserved      = ($phoneFlags >> 24) & 0xff;
        $record{phoneLabel}{phone1} = $phoneTypes[0];
        $record{phoneLabel}{phone2} = $phoneTypes[1];
        $record{phoneLabel}{phone3} = $phoneTypes[2];
        $record{phoneLabel}{phone4} = $phoneTypes[3];
        $record{phoneLabel}{phone5} = $phoneTypes[4];
        $record{phoneLabel}{display} = $dispPhone;
        $record{phoneLabel}{reserved} = $reserved;
        # Get the relevant fields
        $fieldMap & 0x0001 and $record{fields}{name} = shift @fields;
        $fieldMap & 0x0002 and $record{fields}{firstName} =
                shift @fields;
        $fieldMap & 0x0004 and $record{fields}{company} = shift @fields;
        $fieldMap & 0x0008 and $record{fields}{phone1} = shift @fields;
        $fieldMap & 0x0010 and $record{fields}{phone2} = shift @fields;
        $fieldMap & 0x0020 and $record{fields}{phone3} = shift @fields;
        $fieldMap & 0x0040 and $record{fields}{phone4} = shift @fields;
        $fieldMap & 0x0080 and $record{fields}{phone5} = shift @fields;
        $fieldMap & 0x0100 and $record{fields}{address} = shift @fields;
        $fieldMap & 0x0200 and $record{fields}{city} = shift @fields;
        $fieldMap & 0x0400 and $record{fields}{state} = shift @fields;
        $fieldMap & 0x0800 and $record{fields}{zipCode} = shift @fields;
        $fieldMap & 0x1000 and $record{fields}{country} = shift @fields;
        $fieldMap & 0x2000 and $record{fields}{title} = shift @fields;
        $fieldMap & 0x4000 and $record{fields}{custom1} = shift @fields;
        $fieldMap & 0x8000 and $record{fields}{custom2} = shift @fields;
        $fieldMap & 0x10000 and $record{fields}{custom3} = shift @fields;
        $fieldMap & 0x20000 and $record{fields}{custom4} = shift @fields;
        $fieldMap & 0x40000 and $record{fields}{note} = shift @fields;
        delete $record{data};
        return \%record;
}
sub PackRecord
{
        my $self = shift;
        my $record = shift;
        my $retval;
        $retval = pack("N",
                ($record->{phoneLabel}{phone1}    & 0x0f) |
                (($record->{phoneLabel}{phone2}   & 0x0f) <<  4) |
                (($record->{phoneLabel}{phone3}   & 0x0f) <<  8) |
                (($record->{phoneLabel}{phone4}   & 0x0f) << 12) |
                (($record->{phoneLabel}{phone5}   & 0x0f) << 16) |
                (($record->{phoneLabel}{display}  & 0x0f) << 20) |
                (($record->{phoneLabel}{reserved} & 0xff) << 24));
        # Set the flag bits that indicate which fields exist in this
        # record.
        my $fieldMap = 0;
        foreach my $fieldname (qw(name firstName company
                        phone1 phone2 phone3 phone4 phone5
                        address city state zipCode country title
                        custom1 custom2 custom3 custom4
                        note))
        {
                if (defined($record->{fields}{$fieldname}) &&
                    ($record->{fields}{$fieldname} ne ""))
                {
                        $fieldMap |= $fieldMapBits{$fieldname};
                }
                else 
                { 
                        $record->{fields}{$fieldname} = ""; 
                } 
        }
        $retval .= pack("N", $fieldMap);
        my $fields = '';
        my $companyFieldOff = 0;
        $fields .= $record->{fields}{name} . "\0"
                unless $record->{fields}{name} eq "";
        $fields .= $record->{fields}{firstName} . "\0"
                unless $record->{fields}{firstName} eq "";
        if ($record->{fields}{company} ne "")
        {
                $companyFieldOff = length($fields) + 1;
                $fields .= $record->{fields}{company} . "\0"
        }
        # Append each nonempty field in turn to $fields.
        foreach my $fieldname (qw(phone1 phone2 phone3 phone4 phone5
                        address city state zipCode country title
                        custom1 custom2 custom3 custom4 note))
        {
                # Skip empty fields (either blank or undefined).
                next if !defined($record->{fields}{$fieldname});
                next if $record->{fields}{$fieldname} eq "";
                # Append the field (with a terminating NUL)
                $fields .= $record->{fields}{$fieldname} . "\0";
        }
        $retval .= pack("C", $companyFieldOff);
        $retval .= $fields;
        return $retval;
}
1;
__END__
HideShow 25 lines of Pod
=head1 SOURCE CONTROL
The source is in Github:
        http://github.com/briandfoy/p5-Palm/tree/master
         
=head1 AUTHOR
Alessandro Zummo, C<< <a.zummo@towertech.it> >>
Currently maintained by brian d foy, C<< <bdfoy@cpan.org> >>
=head1 SEE ALSO
Palm::PDB(3)
Palm::StdAppInfo(3)
=head1 BUGS
The new() method initializes the AppInfo block with English labels and
"United States" as the country.
=cut