# Pilot Link Sync Abs Conduits

## Pilot Link Sync AbsConduits

This document describes the conduit interface for the pilot-link sync abs conduit.

## Introduction to the Sync Abs Conduit

### What is the sync abs conduit?

The sync abs conduit is designed to free the implementor from having to code the descision logic of the synchronization of a palm pilot database. This is accomplished by having the implementor define a series action based callbacks that are called when appropriate by the sync abs code in pilot-link.

## Sync Abs conduit implementation

### PilotRecords and DesktopRecords

There are two data structures that represent records during the synchronization process, the `PilotRecord` and `DesktopRecord`. The `PilotRecord`, as the name implies, represents records on the pilot device, while the `DesktopRecord` represents records stored in or by a desktop application.

A `PilotRecord` contains the pilot record id, the record category id, dlp status flags (modified, dirty, etc), the raw byte data of the actual record and the length of said raw data. If the record is of one the standard types, for example a datebook entry, the pilot-link unpack methods can be called to interpret the data. If the record is not one of the standard types, the conduit will need to interpret the data itself.

A `DesktopRecord` contains the pilot record id (if known), the record category id and the dlp status flags (modified, dirty, etc). To ease implementation and speed operation, a `DesktopRecord` can be extended by declaring a DesktopRecord to be the first member of another struct and returning a pointer to that other struct when asked to return references to a `DesktopRecord`. This is possible because all `DesktopRecords` are created and destroyed exclusively via the callbacks and thus the implementor can add arbitrary data to such a record.

### SyncHandler and its callbacks

A `SyncHandler` structure contains several standard data fields as well as a series of fifteen function pointers which are the callbacks which need to be implemented.

The standard data fields include the socket descripter (sd) for this particular conduit. Please note that a socket to the pilot is not opened by the sync abs conduit. The name field should contain the name of the database to be synchronized and data field is for the implementor to store any useful and is not used by the sync abs conduit itself.

#### Callbacks

This a a walkthrough of sync abs conduit's fourteen callbacks. Their purpose, importance, usage by the various types of synchronization processes (Fast/Slow sync, copy to/from remote) and how they should behave.

These use normal UNIX api return values, meaning 0 on success, negative values on failure. There is one exception, the compare method which returns 0 if two records are the same and 1 if they are not. However, in this case an error is still represented by a negative return value.

1.     		  int (*PreSync)
       		  SyncHandler *sh
       		  int dbhandle
       		  int *slow

   Description

2. This function is called before the synchronization process begins. In the implementation, the conduit should handle necesseary initialisation, eg. getting the `AppInfo` for the database that the conduit is synchronizing.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dbhandle`

- the dbhandle, as opened by the pilot-link library.

`slow`

- An `int`* pointing that should be set to 1 for a slow sync and 0 for a fast sync.

Returns

- 0 on success, a negative value for failure. And on success, sets *`slow` to the appropriate value.

Needed by

- All

-     		  int (*PostSync)
      		  SyncHandler *sh
      		  int dbhandle

  Description

- This function is called just after the synchronization process ends. In the implementation, the conduit should handle necessary cleanup, eg. doing actual record deletion if it is not done immediately or logging the operation.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dbhandle`

- the dbhandle, as opened by the pilot-link library.

Needed by

- All

-     		  int (*SetPilotID)
      		  SyncHandler *sh
      		  DesktopRecord *dr
      		  guint32 ID

  Description

- Associates a desktop record with a pilot record. This is usually called during synchronization, when a new record is added to the pilot, which assigns an id to the record. This id is then passed on to the conduit via this call.

  This id is also used when iterating over records, where a modification to a local record requires a lookup in the pilot. This lookup is done using this Id, so it is important to save it in the local database.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`local`

- A `DesktopRecord`* pointing to the record to which the id was assigned.

`ID`

- A `guint32` integer containg the id.

Returns

- 0 on success, negative value on error

Needed by

- Fast sync, Slow sync, Merge to pilot, Copy to pilot

-     		  int (*SetStatusCleared)
      		  SyncHandler *sh
      		  DesktopRecord *dr

  Description

- Indicates that the status of the record (usually that it has been changed in some way) should be cleared - usually this is done when the record has been synchronized while iterating over the pilot records.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`local`

- A `DesktopRecord`* pointing to the record whose status should be cleared.

Returns

- 0 on success, negative value on error

Needed by

- Fast sync, Slow sync, Merge to pilot, Copy to pilot

-     		  int (*ForEach)
      		  GnomePilotConduitSyncAbs* conduit
      		  DesktopRecord** dr

  Description

- Returns a succesion of records, all records in the desktop database.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- the iterations "pointer". At first call, *`dr` is NULL. The method should then set `dr` to point at the first desktop record (if any). Upon subsequent calls, point `dr` to the next desktop record, when you reach the end, set `dr` to NULL.

Returns

- 0 on success and *`dr` is set to non NULL or NULL on completion. Returns negative value on error.

Needed by

- FastSync, SlowSync, Copy To Remote

-     		  int (*ForEachModified)
      		  SyncHandler *sh
      		  DesktopRecord** dr

  Description

- Iterates over records that have been modified, which in this context refers to a record that has been changed, deleted or marked as modified.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- the iterations "pointer". At first call, *`dr` is NULL. The method should then set `dr` to point at the first desktop record (if any). Upon subsequent calls, point `dr` to the next desktop record, when you reach the end, set `dr` to NULL.

Returns

- 1 on success and *`local` is set to non NULL, 0 on completion and *`local` is set to NULL, negative value on error.

Needed by

- FastSync, SlowSync, Copy To Remote, Copy From Remote

-     		  int (*Compare)
      		  SyncHandler *sh
      		  PilotRecord* pr
      		  DesktopRecord* dr

  Description

- Compare a desktop record with a pilot record. If both the desktop and pilot records have been modfied, this is called determine if the changes are identical. The meaning of "identical" is determined by the conduit implementor

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`pr`

- Pointer to the pilot record

`dr`

- Pointer to the desktop record

Returns

- 0 if identical in whatever way the conduit decides, positive if different, negative if failure.

Needed by

- FastSync, SlowSync.

-     		  int (*AddRecord)
      		  SyncHandler *sh
      		  PilotRecord* pr

  Description

- Store the information in a pilot record in on the desktop.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`pr`

- pointer to a pilot record whose information is to be stored. The method should copy all the information needed, and either immediately store the record, or queue it for storage.

Returns

- 0 on success, negative value on error

Needed by

- FastSync, SlowSync, Copy From Remote

-     		  int (*ReplaceRecord)
      		  SyncHandler *sh
      		  DesktopRecord* dr
      		  PilotRecord* pr

  Description

- Replace the desktop record information with the information in the pilot record

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- pointer to a desktop record whose information is to be replaced.

`pr`

- pointer to a pilot record whose information is to be used to replace the desktop record's information. The method should copy all the information needed, and either immediately replace the record, or queue it for replacement.

Returns

- 0 on success, negative value on error

Needed by

- FastSync, SlowSync, Copy To Remote, Copy From Remote

-     		  int (*DeleteRecord)
      		  SyncHandler *sh
      		  DesktopRecord* dr

  Description

- This method takes the `dr` record, and removes it from the desktop.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- pointer to a pilot record that should be deleted.

Returns

- 0 on success, a negative value for failure.

Needed by

- FastSync and SlowSync.

-     		  int (*ArchiveRecord)
      		  SyncHandler *sh
      		  DesktopRecord *dr
      		  int archive

  Description

- Sets whether or not a record is archived.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- The a pointer to the desktop record whose "archiveness" is to be set.

`archive`

- 0 if the record should be marked as archived, 1 otherwise.

Returns

- 0 on success, negative value on error

Needed by

- FastSync, SlowSync, Copy To Remote, Copy From Remote

-     		  int (*MatchRecord)
      		  SyncHandler *sh
      		  PilotRecord* pr
      		  DesktopRecord** dr

  Description

- This method takes the `pr` record, and locates the desktop record which is supposed to be the same as the pilot record. The contents of the desktop record belong to the conduit and is not tampered with by the calling method, so you may freely return a pointer to a local static variable.

  The memory allocated by `MatchRecord` is freed by the caller by a call to `FreeMatch`.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`pr`

- pointer to the pilot record to be matched with a desktop record.

`dr`

- `dr` is a pointer to a pointer for storing the record. If no desktop record matching the remote is found, set *`dr` to NULL.

  Only one desktop record should match a remote record.

Returns

- 0 on success, a negative value for failure. And on success, sets *`local` to the appropriate record.

Needed by

- FastSync and SlowSync.

-     		  int (*FreeMatch)
      		  SyncHandler *sh
      		  DesktopRecord** dr

  Description

- This method is responsible for freeing memory allocated by a `MatchRecord` call.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- pointer to a record pointer. This record'ss resources should be freed, and *`dr` set to NULL.

Returns

- 0 on success, negative value on error

Needed by

- FastSync, SlowSync, Copy To Remote, Copy From Remote

-     		  gint  (*Prepare)
      		  SyncHandler *sh
      		  DesktopRecord* dr
      		  PilotRecord* pr

  Description

- From a given desktop record, fill in the given `PilotRecord` record so it can be stored on the pilot.

Parameters

- `sh`

- pointer to the `SyncHandler` controlling this synchronization

`dr`

- A non-null `DesktopRecord`*, pointing to a desktop record created by a call to `ForEach` or `ForEachModified`

`pr`

- A pointer to a `PilotRecord`, which this method should fill out the pilot record version of the desktop record.

Returns

- 0 on success, negative value on error.

Needed by

- FastSync, SlowSync, Copy To Remote

### API Functions

Hi