The SyncAction base class for conduits

All conduits are subclasses of SyncAction, which provides the following methods. The exec method is a pure virtual function and needs to be implemented by each conduit:

• virtual bool exec()=0 ... This function starts the actual processing done by the conduit. It should return false if the processing cannot be initiated, f.ex. because some parameters were not set or a needed library is missing. This will be reported to the user. It should return true if processing is started normally. If processing starts normally, it is the conduit's responsibility to eventually emit syncDone(); if processing does not start normally (ie. exec() returns false) then the environment will deal with syncDone().

• void addSyncLogEntry(const QString &e,bool suppress=false) ... Write a log entry to the pilot. Causes signal logEntry(const char *) to be emitted.
• int pilotSocket()        ... returns the pilot socket (needed if you use your own functions to talk to the handheld. This is not recommended, but necessary in some cases)
• int openConduit()        ... Notify the handheld which conduit is running now.

In addition to these functions the class also has some signals you can emit to display log messages and to indicate that the conduit has finished and KPilot should go on with the next conduit:

• void syncDone(SyncAction *) ... tell KPilot that the conduit has finished. Every conduit that returns true in its exec() method needs to emit this signal, otherwise KPilot will wait forever for the conduit to return.

• void logMessage(const QString &) ... Adds a message to KPilot's log, but not to the handheld's log.
• void logError(const QString &) ... Adds an error message to KPilot's log
• void logProgress(const QString &,int) ... Adds a log message and sets the progress bar to the given percentage.

If your conduit will have to ask the user some question, the handheld needs to be tickled to prevent a timeout while the message box or dialog window is shown. The InteractiveAction class (which is a subclass of SyncAction) can be used as a base class for your conduit in this case. Call startTickle() some time before showing a dialog to the user (we're assuming a local event loop here) so that while the dialog is up and the user is thinking, the pilot stays awake. Afterwards, call stopTickle(). The parameter to startTickle indicates the timeout, in seconds, before signal timeout is emitted. You can connect to that signal, to take down the user interface part if the user isn't reacting. In addition to SyncAction's methods it adds the following methods:

• void tickle() ... Tickles the handheld to reset the timeout counter.
• void startTickle(unsigned count=0) ... start a timer to tickle the handheld in regular intervals
• void stopTickle() ... stop the timer

• int questionYesNo(const QString &question , const QString &caption = QString::null, const QString &key = QString::null, unsigned timeout = 20000) ... Ask a yes-no question of the user. This has a timeout so that you don't wait forever for inattentive users. It's much like KMessageBox::questionYesNo(), but with this extra timeout-on-no-answer feature. Returns a KDialogBase::ButtonCode value - Yes,No or Cancel on timeout. If there is a key set and the user indicates not to ask again, the selected answer (Yes or No) is remembered for future reference.

For conduits that sync one specific database (e.g. "AddressDB" or "TodoDB"), there is the class ConduitAction, which is a child class of SyncAction, and adds the following methods and members:

• PilotDatabase *fDatabase,*fLocalDatabase; ... Pointers to the database on the handheld and the backup database on the harddisk. These are set by openDatabases.
• bool openDatabases(const char *dbName, bool*retrieved=0L) ... opens the database named dbName on the handheld and the backup database on the harddisk (in the directory $KDEHOME/share/apps/kpilot/DBBackup/PalmUserName/). If the backup database does not exist, the current database from the palm is fetched, and *retrieved is set to true.