kpilot/lib

KPilotLink Class Reference

#include <kpilotlink.h>

Inheritance diagram for KPilotLink:

Detailed Description

This is the abstract base class for Handheld interaction.

It tries to define all the behavior that we need; calls to virtual *Impl() functions are used to implement the specific behavior for subclasses.

Definition at line 151 of file kpilotlink.h.


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 , 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
KPilotUser &	getPilotUser ()
const KPilotSysInfo &	getSysInfo ()
virtual const KPilotCard *	getCardInfo (int card=0)=0
virtual void	endOfSync ()=0
virtual void	finishSync ()=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

Constructor & Destructor Documentation

KPilotLink::KPilotLink	(	QObject *	parent = `0`,
		const char *	name = `0`
	)

Constructor.

Use reset() to start looking for a device.

Definition at line 154 of file kpilotlink.cc.

KPilotLink::~KPilotLink ( ) [virtual]

Destructor.

This rudely interrupts any communication in progress.

Definition at line 173 of file kpilotlink.cc.

Member Function Documentation

virtual QString KPilotLink::statusString ( ) const [pure virtual]

Provides a human-readable status string.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual bool KPilotLink::isConnected ( ) const [pure virtual]

True if HotSync has been started but not finished yet (ie.

the physical Pilot is waiting for sync commands)

Implemented in KPilotDeviceLink, and KPilotLocalLink.

QString KPilotLink::pilotPath ( ) const [inline]

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 180 of file kpilotlink.h.

virtual void KPilotLink::reset ( const QString & pilotPath ) [pure virtual]

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.

See also:: reset()
pilotPath()

Implemented in KPilotDeviceLink, and KPilotLocalLink.

bool KPilotLink::event ( QEvent * e ) [virtual]

Implementation detail to handle tickle timeouts.

Definition at line 180 of file kpilotlink.cc.

unsigned int KPilotLink::installFiles	(	const QStringList &	l,
		const bool	deleteFiles
	)

Install the list of files (full paths!) named by l onto the handheld (or whatever this link represents).

If deleteFiles is true, the source files are removed.

Returns:: the number of files successfully installed.

Definition at line 230 of file kpilotlink.cc.

void KPilotLink::addSyncLogEntry	(	const QString &	entry,
		bool	log = `true`
	)

Write a log entry to the handheld.

If log is true, then the signal logMessage() is also emitted. This function is supposed to only write to the handheld's log (with a physical device, that is what appears on screen at the end of a sync).

Definition at line 253 of file kpilotlink.cc.

virtual int KPilotLink::findDatabase	(	const char *	name,
		struct DBInfo *	,
		int	index = `0`,
		unsigned long	type = `0`,
		unsigned long	creator = `0`
	)			`[pure virtual]`

Find a database with the given name (and optionally, type type and creator ID (from pi_mktag) creator, on searching from index index on the handheld.

Fills in the DBInfo structure if found, returns < 0 on error.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual bool KPilotLink::retrieveDatabase	(	const QString &	path,
		struct DBInfo *	db
	)			`[pure virtual]`

Retrieve the database indicated by DBInfo *db into the local file path.

This copies all the data, and you can create a PilotLocalDatabase from the resulting path .

Returns:: true on success

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual int KPilotLink::getNextDatabase	(	int	index,
		struct DBInfo *	db
	)			`[pure virtual]`

Fill the DBInfo structure db with information about the next database (in some ordering) counting from index.

Returns:: < 0 on error

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual DBInfoList KPilotLink::getDBList	(	int	cardno = `0`,
		int	flags = `dlpDBListRAM`
	)			`[pure virtual]`

Returns a list of DBInfo structures describing all the databases available on the link (ie.

device) with the given card number cardno and flags flags. No known handheld uses a cardno other than 0; use flags to indicate what kind of databases to fetch -- dlpDBListRAM or dlpDBListROM.

Returns:: list of DBInfo objects, one for each database

Note:: ownership of the DBInfo objects is passed to the caller, who must delete the objects.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual PilotDatabase* KPilotLink::database ( const QString & name ) [pure virtual]

Return a database object for manipulating the database with name name on the link.

This database may be local or remote, depending on the kind of link in use.

Returns:: pointer to database object, or 0 on error.

Note:: ownership of the database object is given to the caller, who must delete the object in time.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

KPilotUser& KPilotLink::getPilotUser ( ) [inline]

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.

Note:: Do not call this before the sync begins!

Definition at line 268 of file kpilotlink.h.

const KPilotSysInfo& KPilotLink::getSysInfo ( ) [inline]

System information about the handheld.

Ownership is kept by the link. For non-device links, something fake is returned.

Note:: Do not call this before the sync begins!

Definition at line 277 of file kpilotlink.h.

virtual const KPilotCard* KPilotLink::getCardInfo ( int card = 0 ) [pure virtual]

Retrieve information about the data card card; I don't think that any pilot supports card numbers other than 0.

Non-device links return something fake.

This function may return NULL (non-device links or on error).

Note:: Ownership of the KPilotCard object is given to the caller, who must delete it.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual void KPilotLink::endOfSync ( ) [pure virtual]

End the sync in a gracuful manner.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual void KPilotLink::finishSync ( ) [pure virtual]

End the sync in a graceful manner and update the last-sync time and user information on the handheld.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

void KPilotLink::timeout ( ) [signal]

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.

void KPilotLink::logMessage ( const QString & ) [signal]

Signal that a message has been written to the sync log.

void KPilotLink::logError ( const QString & ) [signal]

Signal that an error has occurred, for logging.

void KPilotLink::logProgress	(	const QString &	s,
		int	p
	)			`[signal]`

Signal that progress has been made, for logging purposes.

p is the percentage completed (0 <= s <= 100). The string s is logged as well, if non-Null.

void KPilotLink::deviceReady ( KPilotLink * ) [signal]

Emitted once the user information has been read and the HotSync is really ready to go.

virtual void KPilotLink::close ( ) [pure virtual, slot]

Release all resources, including the master pilot socket, timers, notifiers, etc.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual void KPilotLink::reset ( ) [pure virtual, 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.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

virtual bool KPilotLink::tickle ( ) [pure virtual, slot]

Tickle the underlying device exactly once.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

void KPilotLink::startTickle ( unsigned int timeout = 0 ) [protected]

Start tickling the Handheld (every few seconds).

This lasts until timeout seconds have passed (or forever if timeout is zero).

Note:: Do not call startTickle() twice with no intervening stopTickle().

Definition at line 194 of file kpilotlink.cc.

void KPilotLink::stopTickle ( ) [protected]

Stop tickling the Handheld.

This may block for some time (less than a second) to allow the tickle thread to finish.

Definition at line 219 of file kpilotlink.cc.

virtual bool KPilotLink::installFile	(	const QString &	f,
		const bool	deleteFile
	)			`[protected, pure virtual]`

Install a single file onto the device link.

Full pathname f is used; in addition, if deleteFile is true remove the source file. Returns true if the install succeeded.

The default

Implemented in KPilotDeviceLink, and KPilotLocalLink.

int KPilotLink::openConduit ( ) [protected, virtual]

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.

Returns:: -1 on error

Note:: the default implementation returns 0

Reimplemented in KPilotDeviceLink, and KPilotLocalLink.

Definition at line 266 of file kpilotlink.cc.

int KPilotLink::pilotSocket ( ) const [protected, virtual]

Returns a file handle for raw operations.

Not recommended. On links with no physical device backing, returns -1.

Note:: the default implementation returns -1

Reimplemented in KPilotDeviceLink, and KPilotLocalLink.

Definition at line 271 of file kpilotlink.cc.

virtual void KPilotLink::addSyncLogEntryImpl ( const QString & s ) [protected, pure virtual]

Actually write an entry to the device link.

The message s is guaranteed to be non-Null.

Implemented in KPilotDeviceLink, and KPilotLocalLink.

Member Data Documentation

QString KPilotLink::fPilotPath [protected]

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 349 of file kpilotlink.h.

KPilotUser* KPilotLink::fPilotUser [protected]

User information structure.

Should be filled in when a sync starts, so that conduits can use the information.

Definition at line 399 of file kpilotlink.h.

KPilotSysInfo* KPilotLink::fPilotSysInfo [protected]

System information about the device.

Filled in when the sync starts. Non-device links need to fake something.

Definition at line 404 of file kpilotlink.h.

The documentation for this class was generated from the following files:

kpilot/lib

KPilotLink Class Reference

Detailed Description

Public Slots

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

kpilot/lib

API Dox