kpilot/lib
KPilotDeviceLink Class Reference
#include <kpilotlink.h>
Detailed Description
A class that handles some aspects of communication with the 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 handle().
The KPilotLink class was originally a kind of C++ wrapper for the pilot-link library. It grew and grew and mutated until it was finally cleaned up again in 2001. In the meantime it had become something that wrapped a lot more than just pilot-link.
Definition at line 94 of file kpilotlink.h.
Public Types | |
Init | |
WaitingForDevice | |
FoundDevice | |
CreatedSocket | |
DeviceOpen | |
AcceptedDevice | |
SyncDone | |
PilotLinkError | |
WorkaroundUSB | |
enum | LinkStatus { Init, WaitingForDevice, FoundDevice, CreatedSocket, DeviceOpen, AcceptedDevice, SyncDone, PilotLinkError, WorkaroundUSB } |
Public Slots | |
bool | tickle () const |
void | close () |
void | reset () |
Signals | |
void | timeout () |
void | deviceReady (KPilotDeviceLink *) |
void | logEntry (const char *) |
void | logMessage (const QString &) |
void | logError (const QString &) |
void | logProgress (const QString &, int) |
Public Member Functions | |
KPilotDeviceLink (QObject *parent=0, const char *name=0, const QString &tempDevice=QString::null) | |
virtual | ~KPilotDeviceLink () |
LinkStatus | status () const |
virtual QString | statusString () const |
bool | getConnected () const |
virtual bool | event (QEvent *e) |
QString | pilotPath () const |
void | reset (const QString &pilotPath) |
void | setWorkarounds (bool usb) |
void | setTempDevice (const QString &device) |
int | installFiles (const QStringList &, const bool deleteFiles=true) |
KPilotUser * | getPilotUser () |
KPilotSysInfo * | getSysInfo () |
KPilotCard * | getCardInfo (int card=0) |
void | endOfSync () |
void | finishSync () |
int | getNextDatabase (int index, struct DBInfo *) |
int | findDatabase (const char *name, struct DBInfo *, int index=0, long type=0, long creator=0) |
bool | retrieveDatabase (const QString &path, struct DBInfo *db) |
QPtrList< DBInfo > | getDBList (int cardno=0, int flags=dlpDBListRAM) |
QDateTime | getTime () |
bool | setTime (const time_t &pctime) |
unsigned long | ROMversion () const |
unsigned long | majorVersion () const |
unsigned long | minorVersion () const |
Static Public Member Functions | |
static QString | statusString (LinkStatus l) |
Static Public Attributes | |
static const unsigned int | TickleTimeoutEvent = 1066 |
Protected Types | |
OpenMessage = 1 | |
OpenFailMessage = 2 | |
enum | { OpenMessage = 1, OpenFailMessage = 2 } |
Protected Slots | |
void | openDevice () |
void | acceptDevice () |
Protected Member Functions | |
void | startTickle (unsigned int timeout=0) |
void | stopTickle () |
bool | open (QString device=QString::null) |
void | checkDevice () |
void | shouldPrint (int, const QString &) |
int | pilotSocket () const |
bool | installFile (const QString &, const bool deleteFile=true) |
void | addSyncLogEntry (const QString &entry, bool log=true) |
int | openConduit () |
Protected Attributes | |
int | messages |
int | messagesMask |
KPilotUser * | fPilotUser |
KPilotSysInfo * | fPilotSysInfo |
Static Protected Attributes | |
static const int | messagesType |
Friends | |
class | SyncAction |
Member Enumeration Documentation
anonymous enum [protected] |
Some messages are only printed once and are suppressed after that.
These are indicated by flag bits in messages.
Definition at line 324 of file kpilotlink.h.
The link behaves like a state machine most of the time: it waits for the actual device to become available, and then becomes ready to handle syncing.
Definition at line 123 of file kpilotlink.h.
Constructor & Destructor Documentation
KPilotDeviceLink::KPilotDeviceLink | ( | QObject * | parent = 0 , |
|
const char * | name = 0 , |
|||
const QString & | tempDevice = QString::null | |||
) |
Creates a pilot link that can sync to the pilot.
Call reset() on it to start looking for a device.
Definition at line 119 of file kpilotlink.cc.
KPilotDeviceLink::~KPilotDeviceLink | ( | ) | [virtual] |
Destructor.
This rudely ends the communication with the handheld.
Definition at line 150 of file kpilotlink.cc.
Member Function Documentation
void KPilotDeviceLink::acceptDevice | ( | ) | [protected, slot] |
Called when the device is opened *and* activity occurs on the device.
This indicates the beginning of a hotsync.
Definition at line 510 of file kpilotlink.cc.
void KPilotDeviceLink::addSyncLogEntry | ( | const QString & | entry, | |
bool | log = true | |||
) | [protected] |
Write a log entry to the pilot.
Note that the library function takes a char *, not const char * (which is highly dubious). Causes signal logEntry(const char *) to be emitted if log
is true.
Definition at line 893 of file kpilotlink.cc.
void KPilotDeviceLink::checkDevice | ( | ) | [protected] |
Check for device permissions and existence, emitting warnings for weird situations.
This is primarily intended to inform the user.
Definition at line 238 of file kpilotlink.cc.
void KPilotDeviceLink::close | ( | ) | [slot] |
Release all resources, including the master pilot socket, timers, notifiers, etc.
Definition at line 159 of file kpilotlink.cc.
void KPilotDeviceLink::deviceReady | ( | KPilotDeviceLink * | ) | [signal] |
Emitted once the user information has been read and the HotSync is really ready to go.
bool KPilotDeviceLink::getConnected | ( | ) | const [inline] |
True if HotSync has been started but not finished yet (ie.
the physical Pilot is waiting for sync commands)
Definition at line 148 of file kpilotlink.h.
KPilotUser* KPilotDeviceLink::getPilotUser | ( | ) | [inline] |
Returns the user information as set in the KPilot settings dialog.
The user information can also be set by the Pilot, and at the end of a HotSync the two user informations can be synced as well with finishSync -- this writes fPilotUser again, so don't make local copies of the KPilotUser structure and modify them.
Definition at line 427 of file kpilotlink.h.
QDateTime KPilotDeviceLink::getTime | ( | ) |
Get the time from the handheld device into a QDateTime.
Definition at line 1122 of file kpilotlink.cc.
void KPilotDeviceLink::logEntry | ( | const char * | ) | [signal] |
Whenever a conduit adds a Sync log entry (actually, KPilotLink itself adds some log entries itself), this signal is emitted.
void KPilotDeviceLink::logMessage | ( | const QString & | ) | [signal] |
Whenever a conduit adds a Sync log entry (actually, KPilotLink itself adds some log entries itself), this signal is emitted.
unsigned long KPilotDeviceLink::majorVersion | ( | ) | const |
unsigned long KPilotDeviceLink::minorVersion | ( | ) | const |
bool KPilotDeviceLink::open | ( | QString | device = QString::null |
) | [protected] |
Does the low-level opening of the device and handles the pilot-link library initialisation.
Definition at line 308 of file kpilotlink.cc.
int KPilotDeviceLink::openConduit | ( | ) | [protected] |
void KPilotDeviceLink::openDevice | ( | ) | [protected, slot] |
Attempt to open the device.
Called regularly to check if the device exists (to handle USB-style devices).
Definition at line 272 of file kpilotlink.cc.
QString KPilotDeviceLink::pilotPath | ( | ) | const [inline] |
void KPilotDeviceLink::reset | ( | ) | [slot] |
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.
Definition at line 223 of file kpilotlink.cc.
void KPilotDeviceLink::reset | ( | const QString & | pilotPath | ) |
Return the device link to the Init state and try connecting to the given device path (if it's non-empty).
Definition at line 192 of file kpilotlink.cc.
bool KPilotDeviceLink::retrieveDatabase | ( | const QString & | path, | |
struct DBInfo * | db | |||
) |
Retrieve the database indicated by DBInfo *db into the local file path
.
Definition at line 1010 of file kpilotlink.cc.
unsigned long KPilotDeviceLink::ROMversion | ( | ) | const |
void KPilotDeviceLink::setTempDevice | ( | const QString & | device | ) |
sets an additional device, which should be tried as fallback usefull for hotplug enviroments
Definition at line 266 of file kpilotlink.cc.
bool KPilotDeviceLink::setTime | ( | const time_t & | pctime | ) |
void KPilotDeviceLink::setWorkarounds | ( | bool | usb | ) | [inline] |
Special-cases.
Call this after a reset to set device- specific workarounds; the only one currently known is the Zire 31/72 T5 quirk of doing a non-HotSync connect when it's switched on.
Definition at line 260 of file kpilotlink.h.
LinkStatus KPilotDeviceLink::status | ( | ) | const [inline] |
Get the status (state enum) of this link.
- Returns:
- The LinkStatus enum for the link's current state.
Definition at line 138 of file kpilotlink.h.
QString KPilotDeviceLink::statusString | ( | ) | const [virtual] |
Get a human-readable string for the status of this object.
Definition at line 956 of file kpilotlink.cc.
QString KPilotDeviceLink::statusString | ( | LinkStatus | l | ) | [static] |
bool KPilotDeviceLink::tickle | ( | ) | const [slot] |
Tickle 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 691 of file kpilotlink.cc.
Member Data Documentation
const int KPilotDeviceLink::messagesType [static, protected] |
The documentation for this class was generated from the following files: