kpilot/lib
KPilotLink Class Reference
#include <kpilotlink.h>
Inheritance diagram for KPilotLink:

Detailed Description
KPilotLink handles some aspects of communication with a Handheld.A KPilotLink object represents a connection to a device (which may be active or inactive -- the latter in cases where the link is waiting for a device to show up). The object handles waiting, protocol initialization and some general tasks such as getting system information or user data.
The actual communication with the handheld should use the PilotDatabase methods or use pilot-link dlp_* functions directly on the file descriptor returned by handle().
Implementations of this abstract class are KPilotDeviceLink (for real physical devices) and KPilotLocalLink (for devices represented by an on-disk directory).
General
A KPilotLink object (or one of its subclasses) represents a single (potential) link to a handheld device. The handheld device may be a real physical one (subclass KPilotDeviceLink) or a virtual one (subclass KPilotLocalLink). Every KPilotLink is associated with exactly one identifier for what device it is attached to. Physical devices have physical locations as interpreted by libpisock -- /dev/ttyUSB0 for instance, or net:any -- while virtual devices are associated with a location in the filesystem.A particular KPilotLink object may be connected -- communicating with a device -- or not. For physical devices, that means that the device is attached to the system (for USB-connected devices, think of it as a metaphor in the case of net:any) and that the HotSync button has been pressed. Virtual devices are immediately connected on creation, since there is no sensible "not connected" state. A connected KPilotLink has access to the data on the handheld and can give that data to the rest of the application.
The data access API is divided into roughly three parts, with tickle handling being a special fourth part (see section below). These are:
- Message logging
- System information access
- Database access
Lifecycle
The life-cycle of a KPilotLink object is as follows:# Object is created (one of the concrete subclasses, anyway) # Object gets a location assigned through reset(const QString &) # Object is connected to the handheld device (somehow, depends on subclass) # Object emits signal deviceReady()
After this, the application is free to use the API to access the information from the handheld. When the device connection is no longer needed, call either endOfSync() or finishSync() to wrap up the communications. The object remains alive and may be re-used by calling reset() to use the same location or reset(const QString &) to give it a new location.
handling.
During a HotSync, the Pilot expects to be kept awake by (nearly) continuous communication with the PC. The Pilot doesn't like long periods of inactivity, since they drain the batteries while the communications hardware is kept powered up. If the period of inactivity is too long, the Pilot times out, shuts down the communication, and the HotSync is broken.Sometimes, however, periods of inactivity cannot be avoided -- for instance, if you _have_ to ask the user something during a sync, or if you are fetching a large amount of data from a slow source (libkabc can do that, if your addressbook is on an LDAP server). During these periods of inactivity (as far as the Pilot can tell), you can "tickle" the Pilot to keep it awake. This prevents the communications from being shut down. It's not a good idea to do this all the time -- battery life and possible corruption of the dlp_ communications streams. Hence, you should start and stop tickling the Pilot around any computation which:
- may take a long time
- does not in itself ever communicate directly with the Pilot
You can call slot tickle() whenever you like just to do a dlp_tickle() call on the Pilot. It will return true if the tickle was successful, false otherwise (this can be used to detect if the communication with the Pilot has shut down for some reason).
The protected methods startTickle() and stopTickle() are intended to be called only from SyncActions -- I can't think of any other legitimate use, since everything being done during a HotSync is done via subclasses of SyncActions anyway, and SyncAction provides access to these methods though its own start- and stopTickle().
Call startTickle with a timeout in seconds, or 0 for no timeout. This timeout is _unrelated_ to the timeout in the Pilot's communications. Instead, it indicates how long to continue tickling the Pilot before emitting the timeout() signal. This can be useful for placing an upper bound on the amount of time to wait for, say, user interaction -- you don't want an inattentive user to drain the batteries during a sync because he doesn't click on "Yes" for some question. If you pass a timeout of 0, the Pilot will continue to be tickled until you call stopTickle().
Call stopTickle() to stop tickling the Pilot and continue with normal operation. You must call stopTickle() before calling anything else that might communicate with the Pilot, to avoid corrupting the dlp_ communications stream. (TODO: Mutex the heck out of this to avoid this problem). Note that stopTickle() may hang up the caller for a small amount of time (up to 200ms) before returning.
event() and TickleTimeoutEvent are part of the implementation of tickling, and are only accidentally visible.
Signal timeout() is emitted if startTickle() has been called with a non-zero timeout and that timeout has elapsed. The tickler is stopped before timeout is emitted.
Definition at line 171 of file kpilotlink.h.
Public Types | |
typedef QValueList< struct DBInfo > | DBInfoList |
enum | EndOfSyncFlags { NoUpdate, UpdateUserInfo } |
enum | CustomEvents { EventTickleTimeout = 1066 } |
Public Slots | |
virtual void | close ()=0 |
virtual void | reset ()=0 |
virtual bool | tickle ()=0 |
Signals | |
void | timeout () |
void | logMessage (const QString &) |
void | logError (const QString &) |
void | logProgress (const QString &s, int p) |
void | deviceReady (KPilotLink *) |
Public Member Functions | |
KPilotLink (QObject *parent=0, const char *name=0) | |
virtual | ~KPilotLink () |
virtual QString | statusString () const =0 |
virtual bool | isConnected () const =0 |
QString | pilotPath () const |
virtual void | reset (const QString &pilotPath)=0 |
virtual bool | event (QEvent *e) |
unsigned int | installFiles (const QStringList &l, const bool deleteFiles) |
void | addSyncLogEntry (const QString &entry, bool log=true) |
virtual int | findDatabase (const char *name, struct DBInfo *info, int index=0, unsigned long type=0, unsigned long creator=0)=0 |
virtual bool | retrieveDatabase (const QString &path, struct DBInfo *db)=0 |
virtual int | getNextDatabase (int index, struct DBInfo *db)=0 |
virtual DBInfoList | getDBList (int cardno=0, int flags=dlpDBListRAM)=0 |
virtual PilotDatabase * | database (const QString &name)=0 |
virtual PilotDatabase * | database (const DBInfo *info) |
KPilotUser & | getPilotUser () |
const KPilotSysInfo & | getSysInfo () |
virtual const KPilotCard * | getCardInfo (int card=0)=0 |
virtual void | endSync (EndOfSyncFlags f)=0 |
Protected Member Functions | |
void | startTickle (unsigned int timeout=0) |
void | stopTickle () |
virtual bool | installFile (const QString &f, const bool deleteFile)=0 |
virtual int | openConduit () |
virtual int | pilotSocket () const |
virtual void | addSyncLogEntryImpl (const QString &s)=0 |
Protected Attributes | |
QString | fPilotPath |
KPilotUser * | fPilotUser |
KPilotSysInfo * | fPilotSysInfo |
Friends | |
class | SyncAction |
Member Typedef Documentation
|
A list of DBInfo structures.
Definition at line 177 of file kpilotlink.h. |
Member Enumeration Documentation
|
Custom events we can be handling. .. Definition at line 367 of file kpilotlink.h. |
|
When ending the sync, you can do so gracefully, updating the last-sync time to indicate a successful sync and setting the user name on the device, or you can skip that (for unsuccessful syncs, generally).
Definition at line 359 of file kpilotlink.h. |
Constructor & Destructor Documentation
|
Constructor. Use reset() to start looking for a device. Definition at line 140 of file kpilotlink.cc. |
|
Destructor. This rudely interrupts any communication in progress. It is best to call endOfSync() or finishSync() before destroying the device. Definition at line 165 of file kpilotlink.cc. |
Member Function Documentation
|
Write a log entry to the handheld.
If Definition at line 244 of file kpilotlink.cc. |
|
Actually write an entry to the device link.
The message Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Release all resources, including the master pilot socket, timers, etc.
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Return a database object for manipulating the database with the name stored in the DBInfo structure The default version goes through method database( const QString & ), above.
Reimplemented in KPilotDeviceLink. Definition at line 267 of file kpilotlink.cc. |
|
Return a database object for manipulating the database with name This database may be local or remote, depending on the kind of link in use.
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Emitted once the user information has been read and the HotSync is really ready to go.
|
|
End the sync in a gracuful manner.
If |
|
Allows our class to receive custom events that our threads will be giving to us, including tickle timeouts and device communication events.
Reimplemented in KPilotDeviceLink. Definition at line 172 of file kpilotlink.cc. |
|
Find a database with the given
Fills in the DBInfo structure
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Retrieve information about the data card Non-device links return something fake. This function may return NULL (non-device links or on error).
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Returns a list of DBInfo structures describing all the databases available on the link (ie.
device) with the given card number
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Fill the DBInfo structure
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Retrieve the user information from the device. Ownership is kept by the link, and at the end of a sync the user information is synced back to the link -- so it may be modified, but don't make local copies of it.
Definition at line 323 of file kpilotlink.h. |
|
System information about the handheld. Ownership is kept by the link. For non-device links, something fake is returned.
Definition at line 335 of file kpilotlink.h. |
|
Install a single file onto the device link.
Full pathname Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Install the list of files (full paths!) named by
If
Definition at line 221 of file kpilotlink.cc. |
|
True if HotSync has been started but not finished yet (ie. the physical Pilot is waiting for sync commands) Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Signal that an error has occurred, for logging.
|
|
Signal that a message has been written to the sync log.
|
|
Signal that progress has been made, for logging purposes.
|
|
Notify the Pilot user that a conduit is running now. On real devices, this prints out (on screen) which database is now opened; useful for progress reporting.
Reimplemented in KPilotDeviceLink, and KPilotLocalLink. Definition at line 257 of file kpilotlink.cc. |
|
Information on what kind of device we're dealing with. A link is associated with a path -- either the node in /dev that the physical device is attached to, or an IP address, or a filesystem path for local links. Whichever is being used, this function returns its name in a human-readable form. Definition at line 207 of file kpilotlink.h. |
|
Returns a file handle for raw operations. Not recommended. On links with no physical device backing, returns -1.
Reimplemented in KPilotDeviceLink, and KPilotLocalLink. Definition at line 262 of file kpilotlink.cc. |
|
Assuming things have been set up at least once already by a call to reset() with parameters, use this slot to re-start with the same settings.
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Return the device link to the Init state and try connecting to the given device path (if it's non-empty). What the path means depends on the kind of link we're instantiating.
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Retrieve the database indicated by DBInfo
This copies all the data, and you can create a PilotLocalDatabase from the resulting
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Start tickling the Handheld (every few seconds).
This lasts until
Definition at line 186 of file kpilotlink.cc. |
|
Provides a human-readable status string.
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
Stop tickling the Handheld. This may block for some time (less than a second) to allow the tickle thread to finish. Definition at line 210 of file kpilotlink.cc. |
|
Tickle the underlying device exactly once.
Implemented in KPilotDeviceLink, and KPilotLocalLink. |
|
A timeout associated with tickling has occurred. Each time startTickle() is called, you can state how long tickling should last (at most) before timing out. You can only get a timeout when the Qt event loop is running, which somewhat limits the usefulness of timeouts. |
Member Data Documentation
|
Path of the device special file that will be used. Usually /dev/pilot, /dev/ttySx, or /dev/usb/x. May be a filesystem path for local links. Definition at line 432 of file kpilotlink.h. |
|
System information about the device. Filled in when the sync starts. Non-device links need to fake something. Definition at line 492 of file kpilotlink.h. |
|
User information structure. Should be filled in when a sync starts, so that conduits can use the information. Definition at line 486 of file kpilotlink.h. |
The documentation for this class was generated from the following files: