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

    use ColdSync;
    use ColdSync::SPC;

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

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

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

CW$err is the DLP return status; CW@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.

        $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 CWsize field indicates the size of the database information block, and is not at all useful here.

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

The CWversion field indicates the version of the database.

The CWmodnum 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 CWname field gives the name of the database.

CW$dbinfo->{ctime}, CW$dbinfo->{mtime}, and CW$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}

        $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 CWlocalization_ID field is.

The CWproduct_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 CWDLP_version indicates the version of the DLP protocol that the Palm implements.

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

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

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

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

CW$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, CWdlp_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, CWdlp_OpenDB returns CWundef.

        dlp_CloseDB($dbh);

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

        dlp_DeleteDB($dbh);

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

        $dbrecords = dlp_ReadOpenDBInfo($dbh);

Reads the info from the current database associated with the database handle CW$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($dbh);

        dlp_AddSyncLogEntry($dbh);

Adds an entry in the sync log for the database associated with the database handle CW$dbh.

        $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($dbh, $recordid, $flags);

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

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

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

        dlp_DeleteAllRecords($dbh);

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

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

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

CW$offset is the offset at which to begin reading, relative to the beginning of the record, with 0 being the beginning of the record. CW$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'}

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

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

CW$offset is the offset at which to begin reading, relative to the beginning of the record, with 0 being the beginning of the record. CW$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'}

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

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

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

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

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

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

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

Returns the DLP error code.

        $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.

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

Sets the time on the Palm as indicated.

CW$year must be a 4 digit number, and is not 1900 subtracted, as returned from localtime(). CW$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.

ColdSync(3)

Palm::PDB(3)

ColdSync Conduits: Specification and Hacker's Guide

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

``SPC'' is a stupid name.