kpilot/lib

KPilotDeviceLink Class Reference

#include <kpilotlink.h>

List of all members.


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

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

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.

enum KPilotDeviceLink::LinkStatus
 

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
 

Get the major PalmOS version number.

Definition at line 1149 of file kpilotlink.cc.

unsigned long KPilotDeviceLink::minorVersion  )  const
 

Get the minor PalmOS version number.

Definition at line 1154 of file kpilotlink.cc.

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]
 

Notify the Pilot user which conduit is running now.

Definition at line 912 of file kpilotlink.cc.

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]
 

Information on what kind of device we're dealing with.

Definition at line 245 of file kpilotlink.h.

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.

unsigned long KPilotDeviceLink::ROMversion  )  const
 

Get the version number from the handheld.

Definition at line 1142 of file kpilotlink.cc.

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  ) 
 

Set the time on the handheld to the give QDateTime.

Definition at line 1133 of file kpilotlink.cc.

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]
 

Get a human-readable string for the given status l.

Definition at line 917 of file kpilotlink.cc.

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]
 

Initial value:

    (int)OpenFailMessage

Definition at line 1160 of file kpilotlink.cc.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys