PHP-PDB: Address Book

General
Main Page
Basic Use Custom Formats Extra Info Credits
Modules
Address Book Datebook DOC List Memo Pad MobileDB SmallBASIC Todo
Examples
Bookmark Test Spade Twister
SourceForge
Download Project Page Mailing Lists Bug Reporting

Address entries have a lot of data associated with them. Because of this, there is a somewhat complex way of getting to that data. However, I'll try to explain it thoroughly and show examples so that you don't get lost.

If you install a database created with this class onto your handheld, it will overwrite the one that already exists on your handheld. This is because a new database will have the same name as the current database on your handheld and you can't change the name of the database otherwise the application won't work. This is obviously irritating -- please keep this in mind. An ideal use for this PHP class would be for talking to a conduit, where the conduit would upload the current data, the server would parse it and add/modify/delete entries with this class, the server would send the modified file back to the conduit, and the conduit would replace the device's database with the modified one.

Including into your program

include 'php-pdb.inc';
include 'modules/addrbook.inc';

Creating a new database

Since an address book has a specified type, creator, and name, the class takes care of knowing what they are. Creation of a new contacts database is trivial.

$DB = new PalmDatebook();
// or
$DB = new PalmDatebook($Country);

The country can be passed in order to facilitate i18n. It is optional and will default to PDB_ADDR_COUNTRY_DEFAULT (which is set to PDB_ADDR_COUNTRY_UNITED_STATES in addrbook.inc -- but you can change it to affect your entire site if you wish). A list of all countries is in addrbook.inc.

Writing the database

This is the same as the base class. See Basic Use for more information.

Loading the database

This is the same as the base class. See Basic Use for more information.

Category Support and Record Attributes

This supports categories and attributes. See Basic Use for more information.

Other functions

GetRecordRaw() SetRecordRaw()

Please see Basic Use for how to use these functions. You use both of these to get/set records in the database.

NewRecord()

Returns an array with some default data for a new Datebook record. Does not actually add the record. Use SetRecordRaw() for that.

SetFieldLabels($list)
GetFieldLabels()

Get/set the field labels as an associative array. The field labels define what are shown when you view and edit an entry in your address book. If you want "Last name:" to show up as "Surname:" and "Company:" as "Business:", you change them in this array.

// Load the current set of field labels
$labels = GetFieldLabels();

// If you were to run this code ...
// foreach ($labels as $key => $val) {
// echo "$key => $val \n";
// }
// the results would look like this:
//
// LastName => Last 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

// Let's change a few things around
$labels['LastName'] = 'Last Name'; // Capitalize the "Name" part
$labels['FirstName'] = 'First Name'; // Capitalize the "Name" part
$labels['Phone5'] = 'Email'; // Remove hyphen
$labels['Phone8'] = 'Cellular'; // "Mobile" -> "Cellular"

// Save the changes
$pdb->SetFieldLabels($labels);

Record Format

The data for the GetRecordRaw and the data returned from SetRecordRaw is a specially formatted array, as detailed below. Optional values can be set to '' or not defined. If an optional value is anything else (including zero), it is considered to be set. At least one optional value should be specified. If no optional values are specified, then 'Empty Record' will be displayed as the last name.

Key	Example	Description
LastName	Duck	The contact's last name
FirstName	Daffy	The contact's first name
Company	PHP-PDB Inc.	The name of the company
Phone1	867-5309	What goes in the first phone/email/etc field.
...	...	Same goes for Phone2, Phone3, Phone4 ...
Phone5	dduck@toon.com	What goes in the last phone/email/etc field.
Phone1Type	PDB_ADDR_LABEL_WORK	The type of the first phone record
...	...	Same goes for Phone2Type, Phone3Type, Phone4Type ... (see below)
Phone5Type	PDB_ADDR_LABEL_EMAIL	What type of data is in Phone5
Address	Duck street 25	The address
City	Toon City	The city
State	FL	The state of the contact
ZipCode	12345	The post office zip code for the contact
Country	Toon Land	The contact's country
Title	Sir	The title of the contact
Custom1	Birth Date	Extra information
...	...	Same goes for Custom2, Custom3
Custom4	Whatever	The last extra information field
Note	Quack.	Notes for the contact
Display	1	Which phone# entry to display on the list screen
Reserved	'' (empty string)	Unknown

The Phone#Type keys assocaite the five Phone# strings with the proper labels that are defined with GetFieldLabels and SetFieldLabels. There are eight possible strings that Phone# can be associated with. Below is a table showing the default values for the eight phone labels. See the SetFieldLabels() and GetFieldLabels() for information on how to change the text that shows up for the label.

Array Index	Defined Variable	Default Value
0	PDB_ADDR_LABEL_WORK	Work
1	PDB_ADDR_LABEL_HOME	Home
2	PDB_ADDR_LABEL_FAX	Fax
3	PDB_ADDR_LABEL_OTHER	Other
4	PDB_ADDR_LABEL_EMAIL	E-Mail
5	PDB_ADDR_LABEL_MAIN	Main
6	PDB_ADDR_LABEL_PAGER	Pager
7	PDB_ADDR_LABEL_MOBILE	Mobile

Let's assume that for your contact, you have two work numbers, a fax number, an email address, and a cell phone number (in that order). You'd want to associate them with the correct labels for the numbers, and the below table uses this information for its example. Additionally, in the record array is 'Display', which is the index of the array to display. The example will assume you want the email address displayed.

// Set the other aspects of $record before this ...
// For example, $record['FirstName'] = 'Donald';
// Also set the Phone# entries before here

// Associate Phone1 and Phone2 with the Work label
$record['Phone1'] = PDB_ADDR_LABEL_WORK;
$record['Phone2'] = PDB_ADDR_LABEL_WORK;

// Phone3 is a fax number, Phone4 is an email, Phone5 is a cell phone number
$record['Phone3'] = PDB_ADDR_LABEL_FAX;
$record['Phone4'] = PDB_ADDR_LABEL_EMAIL;
$record['Phone5'] = PDB_ADDR_LABEL_MOBILE;

// Display the email address on the list screen of the address book app
$record['Display'] = 3;

For the attributes and categories, see Basic Use for the class.

Example

// How to write a database
$addr = new PalmAddress();

// Remember -- category 0 is reserved.
$categories = array(1 => 'VIP', 'AAA', 'Inicial');
$addr->SetCategoryList($categories);
$fields = array('LastName' => 'Pascual',
'FirstName' => 'Eduardo',
'Phone1' => '21221552',
'Phone2' => '58808912',
'Phone5' => 'epascual at cie.com.mx',
'Address' => 'Hda. la Florida 10A',
'City' => 'Izcalli');
$addr->SetRecordRaw($fields);
$addr->GoToRecord('+1');
$fields = array('LastName' => 'de tal',
'FirstName' => 'fulanito',
'Address' => 'Direccion',
'Phone1' => '21232425',
'Phone1Type' => PDB_ADDR_LABEL_HOME,
'Phone2' => 'fulanito at dondesea.com',
'Phone2Type' => PDB_ADDR_LABEL_EMAIL,
'Phone3Type' => PDB_ADDR_LABEL_WORK,
'Phone4Type' => PDB_ADDR_LABEL_FAX,
'Phone5Type' => PDB_ADDR_LABEL_OTHER,
'Display' => 1);
$addr->SetRecordRaw($fields);
$addr->SetRecordAttrib(PDB_RECORD_ATTRIB_PRIVATE |
1); // Category 1, private record
$fp = fopen('./pdbs/addr.pdb','wb');
$addr->WriteToFile($fp);
fclose($fp);

// How to read a database
$addr = new PalmAddress();
$fp = fopen('./address.pdb','r');
$addr->ReadFile($fp);
fclose($fp);
echo "Name: $addr->Name \n";
echo "Type: $addr->TypeID ";
echo "Creator: $addr->CreatorID \n";
echo "Attributes: $addr->Attributes \n";
echo "Version: $addr->Version \n";
echo "ModNum: $addr->ModNumber \n";
echo "CreationTime: $addr->CreationTime \n";
echo "ModTime: $addr->ModificationTime \n";
echo "BackTime: $addr->BackupTime \n";
echo "NumRec: ".$addr->GetRecordCount()." \n";
$recids = $addr->GetRecordIDs();
$cats = $addr->GetCategoryList();
foreach ($recids as $ID) {
$record = $addr->GetRecordRaw($ID);
echo "Record $ID: ";
$attrib = $addr->GetRecordAttrib($ID);
echo "- Category number: " . ($attrib & PDB_CATEGORY_MASK) . " = " .
$cats[$attrib & PDB_CATEGORY_MASK]['Name'] . " \n";
echo "- Private: " .
(($attrib & PDB_RECORD_ATTRIB_PRIVATE) ? "Yes" : "No") ." \n";
echo " Fields: \n";
foreach ($record as $reck => $rec) {
echo "-- $reck => $rec \n";
}
}
echo "Field Labels ";
$labels = $addr->GetFieldLabels();
foreach ($labels as $k => $v) {
echo "$k = $v ";
}