ColdSync::SPC(3p)

NAME
SPC - Allows ColdSync conduits to communicate directly with the Palm.

SYNOPSIS
    use ColdSync;
    use ColdSync::SPC;

DESCRIPTION
The SPC package includes functions for sending Serialized Request Protocol (SPC) requests in ColdSync conduits.

FUNCTIONS

  dlp_version
        if( dlp_version >= 1.2 ) {
                call_vfs_function();
        }

Returns the version of the DLP protocol supported by the PDA.

  dlp_req
    ($err, @argv) = dlp_req($reqno, @args)

Sends a DLP request over SPC. $reqno is the DLP request number; @args is the array of DLP arguments.

$err is the DLP return status; @argv is the array of values returned from the Palm.

This is a fairly low-level function. It is much easier to use one of the DLP wrapper functions. However, not every DLP function has been implemented yet.

  spc_get_dbinfo
        $dbinfo = spc_get_dbinfo();

Returns a reference to a hash containing information about the database currently being synchronized:

        $dbinfo->{size}
        $dbinfo->{misc_flags}
        $dbinfo->{db_flags}
        $dbinfo->{type}
        $dbinfo->{creator}
        $dbinfo->{version}
        $dbinfo->{modnum}
        %{$dbinfo->{ctime}}
        %{$dbinfo->{mtime}}
        %{$dbinfo->{baktime}}
        $dbinfo->{db_index}
        $dbinfo->{name}

The "size" field indicates the size of the database information block, and is not at all useful here.

The "creator" and "type" fields are four-character strings specifying the creator and type of the databse.

The "version" field indicates the version of the database.

The "modnum" field indicates the modification number of the database. Each time the database is modified, this number is incremented. Since there is no mechanism within ColdSync to keep this number consistent between the Palm and the desktop, this number is not very useful.

The "name" field gives the name of the database.

"$dbinfo->{ctime}", "$dbinfo->{mtime}", and "$dbinfo->{baktime}" indicate the creation, modification, and backup time of the database. They are all of the following form:

        $dbinfo->{ctime}{year}
        $dbinfo->{ctime}{month}
        $dbinfo->{ctime}{day}
        $dbinfo->{ctime}{hour}
        $dbinfo->{ctime}{minute}
        $dbinfo->{ctime}{second}

  dlp_ReadSysInfo
        $sysinfo = dlp_ReadSysInfo();

Returns a reference to a hash containing information about the Palm:

        $sysinfo->{ROM_version}
        $sysinfo->{localization_ID}
        $sysinfo->{product_ID}
The C<ROM_version> field indicates the version of the Palm's ROM.

I don't know what the "localization_ID" field is.

The "product_ID" indicates which particular model of Palm this is.

The following fields may not be returned by all Palms:

        $sysinfo->{DLP_version}
        $sysinfo->{compat_version}
        $sysinfo->{maxrec}

The "DLP_version" indicates the version of the DLP protocol that the Palm implements.

I'm not sure what the "compat_version" field is. I suspect that it gives the earliest version of DLP with which this Palm is compatible.

The "maxrec" field indicates the maximum size of a record or resource.

  dlp_OpenDB
        $dbh = dlp_OpenDB($dbname, $mode);

Opens a database on the Palm. $dbname is a string indicating the name of the database; the name of the current database can be gotten from "spc_get_dbinfo".

$mode indicates how to open the database. It is the bitwise-or of any of the following values:

        0x80            Open for reading
        0x40            Open for writing
        0x20            Exclusive access
        0x10            Show secret records

If successful, "dlp_OpenDB" returns a database handle: a small integer that refers to the database that was just opened. The database handle will be passed to various other functions that operate on the database.

If unsuccessful, "dlp_OpenDB" returns "undef".

  dlp_CreateDB
        $dbh = dlp_CreateDB($creator,$type,$cardno,$flags,$version,$dbname);

Creates and opens a new database called $dbname on the Palm. $creator and $type are the usual Palm database identifiers. $cardno is the card on which the database is created (zero usually meaning RAM). $flags is the database attributes such as read-only, streamable, etc. See the PDB_ATTR_ flags in pdb.h. $version is the database version.

If successful, "dlp_CreateDB" returns a database handle: a small integer that refers to the database that was just opened. The database handle will be passed to various other functions that operate on the database.

If unsuccessful, "dlp_CreateDB" returns "undef".

  dlp_CloseDB
        dlp_CloseDB($dbh);

Closes the database associated with the database handle $dbh (see "dlp_OpenDB").

  dlp_DeleteDB
        dlp_DeleteDB($dbh);

Deletes the database associated with the database handle $dbh (see "dlp_OpenDB").

  dlp_ReadOpenDBInfo
        $dbrecords = dlp_ReadOpenDBInfo($dbh);

Reads the info from the current database associated with the database handle $dbh and returns a reference to a hash containing information about the database:

        $dbrecords->{numrecords}

Returns the number of records in the database.

  dlp_CleanUpDatabase
        dlp_CleanUpDatabase($dbh);

  dlp_AddSyncLogEntry
        dlp_AddSyncLogEntry($text);

Adds the entry $text in the sync log for the database currently being synched.

  dlp_ReadUserInfo
        $user = dlp_ReadUserInfo();

Returns a reference to a hash containing information about the user info.

        $user->{'userid'}
The Palm user id.

        $user->{'viewer'}
I don't know what this is.

        $user->{'lastsyncpc'}
The last pc that the Palm synced with.

        $user->{succsyncdate}{year}
        $user->{succsyncdate}{month}
        $user->{succsyncdate}{day}
        $user->{succsyncdate}{hour}
        $user->{succsyncdate}{minute}
        $user->{succsyncdate}{second}
The last successful sync date, broken down into year, month, day,
hour, minute, second.

        $user->{lastsyncdate}{year}
        $user->{lastsyncdate}{month}
        $user->{lastsyncdate}{day}
        $user->{lastsyncdate}{hour}
        $user->{lastsyncdate}{minute}
        $user->{lastsyncdate}{second}
The last sync date, broken down into year, month, day, hour, minute,
second. If this does not match the last successful sync date then the
last attempt to sync failed.

        $user->{'usernamelen'}
        $user->{'passwordlen'}
The number of characters in the username and the number of characters
in the Palm password.

        $user->{'username'}
        $user->{'password'}
The username and passwrod that is used for syncing.

  dlp_DeleteRecord
        dlp_DeleteRecord($dbh, $recordid, $flags);

Deletes one record of the database associated with the database handle $dbh.

The $recordid is the id of the record to delete.

I don't know what $flags does (you can omit it for now).

  dlp_DeleteAllRecords
        dlp_DeleteAllRecords($dbh);

Deletes all the records from the database associated with the database handle $dbh.

  dlp_ReadRecordById
        $record = dlp_ReadRecordById($dbh, $recordid, $offset, $numbytes);

Returns a reference to a hash containing information about the record specified by $id for the database associated with the database handle $dbh.

$offset is the offset at which to begin reading, relative to the beginning of the record, with 0 being the beginning of the record. $numbytes is the number of characters to read.

        $record->{'id'}
        $record->{'index'}
        $record->{'size'}
        $record->{'attrs'}
        $record->{'category'}
        $record->{'data'}
        $record->{'attributes'}{'deleted'}
        $record->{'attributes'}{'dirty'}
        $record->{'attributes'}{'busy'}
        $record->{'attributes'}{'secret'}
        $record->{'attributes'}{'archived'}

  dlp_ReadRecordByIndex
        $record = dlp_ReadRecordByIndex($dbh, $recordindex, $offset, $numbytes);

Returns a reference to a hash containing information about the record specified by $recordindex for the database associated with the database handle $dbh.

$offset is the offset at which to begin reading, relative to the beginning of the record, with 0 being the beginning of the record. $numbytes is the number of characters to read.

        $record->{'id'}
        $record->{'index'}
        $record->{'size'}
        $record->{'attrs'}
        $record->{'category'}
        $record->{'data'}
        $record->{'attributes'}{'deleted'}
        $record->{'attributes'}{'dirty'}
        $record->{'attributes'}{'busy'}
        $record->{'attributes'}{'secret'}
        $record->{'attributes'}{'archived'}

  dlp_ResetRecordIndex
        dlp_ResetRecordIndex($dbh);

Resets the modified index.

  dlp_ReadNextModifiedRec
        $record = dlp_ReadNextModifiedRec($dbh);

Returns a reference to a hash containing information about the next modified record in the database (since last sync). Fields returned are the same as dlp_ReadRecord. Returns undef when no more modified records are available.

  dlp_ReadNextRecInCategory
        $record = dlp_ReadNextRecInCategory($dbh,$catno);

Returns a reference to a hash containing information about the next record in the database matching the specified category. Fields returned are the same as dlp_ReadRecord. Returns undef when no more records are available.

  dlp_ReadNextModifiedRecInCategory
        $record = dlp_ReadNextModifiedRecInCategory($dbh,$catno);

Returns a reference to a hash containing information about the next modified record in the database matching the specified category. Fields returned are the same as dlp_ReadRecord. Returns undef when no more modified records are available.

  dlp_WriteRecord
        ($err, $retval, $newid) = dlp_WriteRecord($dbh, $id, $data,
                                                  $category, $attributes,
                                                                                                                        $flags);

Writes a record to the open database handle $dbh. If a record with $id already exists, it will be overwritten with the new data. Otherwise, a new record will be created and a new identifier $newid will be created (which may or may not be the same as $id). $data is the raw record bytes, $category is the record category, $attributes is the bitwise record attributes, and $flags are WriteRecord flags.

  dlp_ReadAppBlock
        $appinfo = dlp_ReadAppBlock($dbh [, $offset, $len]);

Reads the AppInfo block of the database associated with database handle $dbh (see "dlp_OpenDB").

$offset is an integer specifying an offset from the beginning of the AppInfo block at which to start reading. $len is the length of the data to return.

If omitted, $offset defaults to 0 (read from the beginning) and $len defaults to -1 (read to the end).

The value returned by "dlp_ReadAppBlock" is a string of binary data. It is not parsed in any way.

  dlp_WriteAppBlock
        $err = dlp_WriteAppBlock($dbh, $appinfo);

Writes a new AppInfo block to the database indicated by database handle $dbh. $appinfo is a string of binary data, the raw AppInfo block; it is not parsed in any way.

Returns the DLP error code.

  dlp_GetSysDateTime
        $datetime = dlp_GetSysDateTime();

Reads the date and time from the Palm. Returns a reference to a hash containing the date, with fields "year", "month", "day", "hour", "minute", "second".

  dlp_SetSysDateTime
        $err = dlp_SetSysDateTime($year, $mon, $day, $hour, $min, $sec);

Sets the time on the Palm as indicated.

$year must be a 4 digit number, and is not 1900 subtracted, as returned from localtime(). $mon must be a 1-offset number (January = 1).

The first argument may be a reference to an hash, using the same format as the one returned by dlp_GetSysDataTime .

Returns the DLP error code.

  dlp_ReadDBList
  my $start = 0;
  while(my $dbinfo = dlp_ReadDBList($card, $flags, $start)) {
    print $dbinfo->{'name'}, "\n";
    $start = $dbinfo->{'last_index'} + 1;
  }

Get the database list from the Palm. $card indicates the card from which to get the list. $start indicates the index at which to start. $flags indicates where to get the database. It's a bitwise mask of the following:

        0x80 from RAM
        0x40 from ROM

The multi mask (0x20) is not supported.

The function is called repeatedly, each time adjusting $start to the next value after the "last_index" field of the returned hash reference. When no more databases are available, undef is returned.

Successful calls return a hash reference containing:

        $dbinfo->{size}
        $dbinfo->{misc_flags}
        $dbinfo->{db_flags}
        $dbinfo->{type}
        $dbinfo->{creator}
        $dbinfo->{version}
        $dbinfo->{modnum}
        %{$dbinfo->{ctime}}
        %{$dbinfo->{mtime}}
        %{$dbinfo->{baktime}}
        $dbinfo->{db_index}
        $dbinfo->{name}

Note that this is a fairly expensive function in terms of communications time. It should be used sparingly and the results, where possible, should be cached.

  dlp_ResetSyncFlags
        dlp_ResetSyncFlags($dbh);

  dlp_FindDBByCreatorType
        my $dbinfo = &dlp_FindDBByCreatorType( $creator, $type );
        my $maildb = &dlp_FindDBByCreatorType( "mail", "DATA", 0 );
        my @books = &dlp_FindDBByCreatorType( undef, "zTXT" );

Fetches a database by a given $creator and $type pair. If either creator or type are undefined, the argument will be taken as a wildcard.

If called in a scalar context, only the first match is returned. If called in an array context, all matches are returned (an array of hashes). Obviously this might be an expensive process if the wildcards match a lot of items (i.e. undef,DATA).

A third argument, $newsearch, will cause the search to be restarted from scratch when true. If zero, the search will be continued from the last position. $newsearch is implied in array context or when missing/undefined.

All the usual database info fields are returned (see dlp_ReadDBList) along with the "cardno" and "localid" fields.

  dlp_FindDBByName
        my $dbinfo = &dlp_FindDBByName( $dbname, $card, $getsize );
        my $maildb = &dlp_FindDBByName( 'MailDB' );

Fetches database info by a given database name $dbname on the specified $card. If $card is undefined, zero is assumed. If $getsize is non-zero, size information will be fetched. Getting database sizes is supposed to be fairly slow, so use with caution.

All the usual database info fields are returned (see dlp_ReadDBList) along with the "cardno" and "localid" fields. If $getsize is set, the following size fields will also be fetched:

                {dbsize}{num_records}
                {dbsize}{total_bytes}
                {dbsize}{data_bytes}
                {dbsize}{appinfo_bytes}
                {dbsize}{sortinfo_bytes}
                {dbsize}{maxrec_size}

SEE ALSO
ColdSync(3)

Palm::PDB(3)

ColdSync Conduits: Specification and Hacker's Guide

AUTHOR
Andrew Arensburger <arensb@ooblick.com> Alessandro Zummo <azummo@towertech.it>

BUGS
``SPC'' is a stupid name.