diff options
Diffstat (limited to 'kpilot/lib/kpilotlink.h')
| -rw-r--r-- | kpilot/lib/kpilotlink.h | 501 |
1 files changed, 0 insertions, 501 deletions
diff --git a/kpilot/lib/kpilotlink.h b/kpilot/lib/kpilotlink.h deleted file mode 100644 index 4389cb8b..00000000 --- a/kpilot/lib/kpilotlink.h +++ /dev/null @@ -1,501 +0,0 @@ -#ifndef _KPILOT_KPILOTLINK_H -#define _KPILOT_KPILOTLINK_H -/* KPilot -** -** Copyright (C) 1998-2001 by Dan Pilone -** Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com> -** Copyright (C) 2006 Adriaan de Groot <groot@kde.org> -** -*/ - -/* -** This program is free software; you can redistribute it and/or modify -** it under the terms of the GNU Lesser General Public License as published by -** the Free Software Foundation; either version 2.1 of the License, or -** (at your option) any later version. -** -** This program is distributed in the hope that it will be useful, -** but WITHOUT ANY WARRANTY; without even the implied warranty of -** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -** GNU Lesser General Public License for more details. -** -** You should have received a copy of the GNU Lesser General Public License -** along with this program in a file called COPYING; if not, write to -** the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, -** MA 02110-1301, USA. -*/ - -/* -** Bug reports and questions can be sent to kde-pim@kde.org -*/ - -#include <pi-dlp.h> - -#include <tqobject.h> -#include <tqvaluelist.h> - -/** @file -* Encapsulates all the communication with the handheld. Also -* does daemon-like polling of the handheld. Interesting status -* changes are signalled. -*/ - -class TQThread; -class KPilotUser; -class KPilotSysInfo; -class KPilotCard; -class PilotDatabase; - - - -/** -* 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 @e 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). -* -* -* @section 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 @em 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 -* -* @section 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 TQString &) -* # 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 TQString &) to give it a new location. -* -* @section 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 @em 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 @em 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. -*/ -class KDE_EXPORT KPilotLink : public QObject -{ -Q_OBJECT -friend class SyncAction; -public: - /** A list of DBInfo structures. */ - typedef TQValueList<struct DBInfo> DBInfoList; - - /** Constructor. Use reset() to start looking for a device. */ - KPilotLink( TQObject *parent = 0, const char *name = 0 ); - - /** Destructor. This rudely interrupts any communication in progress. - * It is best to call endOfSync() or finishSync() before destroying - * the device. - */ - virtual ~KPilotLink(); - - - /** Provides a human-readable status string. */ - virtual TQString statusString() const = 0; - - /** - * True if HotSync has been started but not finished yet - * (ie. the physical Pilot is waiting for sync commands) - */ - virtual bool isConnected() const = 0; - - - /** - * 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. - */ - TQString pilotPath() const - { - return fPilotPath; - } - - /** - * 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 reset() - * @see pilotPath() - */ - virtual void reset(const TQString &pilotPath) = 0; - - /** Allows our class to receive custom events that our threads - * will be giving to us, including tickle timeouts and - * device communication events. - */ - virtual bool event(TQEvent *e); - - /** - * Install the list of files (full paths!) named by @p l - * onto the handheld (or whatever this link represents). - * If @p deleteFiles is true, the source files are removed. - * - * @return the number of files successfully installed. - */ - unsigned int installFiles(const TQStringList &l, const bool deleteFiles); - - /** - * Write a log entry to the handheld. If @p log is true, - * then the signal logMessage() is also emitted. This - * function is supposed to @em only write to the handheld's - * log (with a physical device, that is what appears on - * screen at the end of a sync). - */ - void addSyncLogEntry(const TQString &entry,bool log=true); - - /** - * Find a database with the given @p name (and optionally, - * type @p type and creator ID (from pi_mktag) @p creator, - * on searching from index @p index on the handheld. - * Fills in the DBInfo structure @p info if found. - * - * @return >=0 on success. See the documentation for each - * subclass for particular meanings. - * @return < 0 on error. - */ - virtual int findDatabase(const char *name, - struct DBInfo *info, - int index=0, - unsigned long type=0, - unsigned long creator=0) = 0; - - /** - * Retrieve the database indicated by DBInfo @p *db into the - * local file @p path. This copies all the data, and you can - * create a PilotLocalDatabase from the resulting @p path . - * - * @return @c true on success - */ - virtual bool retrieveDatabase(const TQString &path, struct DBInfo *db) = 0; - - /** - * Fill the DBInfo structure @p db with information about - * the next database (in some ordering) counting from - * @p index. - * - * @return < 0 on error - */ - virtual int getNextDatabase(int index,struct DBInfo *db) = 0; - - /** - * Returns a list of DBInfo structures describing all the - * databases available on the link (ie. device) with the - * given card number @p cardno and flags @p flags. No known - * handheld uses a cardno other than 0; use flags to - * indicate what kind of databases to fetch -- @c dlpDBListRAM - * or @c dlpDBListROM. - * - * @return list of DBInfo objects, one for each database - * @note ownership of the DBInfo objects is passed to the - * caller, who must delete the objects. - */ - virtual DBInfoList getDBList(int cardno=0, int flags=dlpDBListRAM) = 0; - - /** - * Return a database object for manipulating the database with - * name @p name on the link. This database may be local or - * remote, depending on the kind of link in use. - * - * @return 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. - */ - virtual PilotDatabase *database( const TQString &name ) = 0; - - /** - * Return a database object for manipulating the database with - * the name stored in the DBInfo structure @p info . The default - * version goes through method database( const TQString & ), above. - * - * @return pointer to database object, or 0 on error. - * @note ownership of the database object is given to the caller. - */ - virtual PilotDatabase *database( const DBInfo *info ); - - /** - * 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! - */ - KPilotUser &getPilotUser() - { - return *fPilotUser; - } - - /** - * 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! - */ - const KPilotSysInfo &getSysInfo() - { - return *fPilotSysInfo; - } - - /** - * Retrieve information about the data card @p 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. - */ - virtual const KPilotCard *getCardInfo(int card=0) = 0; - - /** - * 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). - */ - enum EndOfSyncFlags { - NoUpdate, ///< Do not update the user info - UpdateUserInfo ///< Update user info and last successful sync date - } ; - - /** - * Custom events we can be handling... - */ - enum CustomEvents { - EventTickleTimeout = 1066 - }; - - /** - * End the sync in a gracuful manner. If @p f is UpdateUserInfo, - * the sync was successful and the user info and last successful sync - * timestamp are updated. - */ - virtual void endSync( EndOfSyncFlags f ) = 0; - -signals: - /** - * 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 timeout(); - - /** Signal that a message has been written to the sync log. */ - void logMessage(const TQString &); - - /** Signal that an error has occurred, for logging. */ - void logError(const TQString &); - - /** - * Signal that progress has been made, for logging purposes. - * @p p is the percentage completed (0 <= s <= 100). - * The string @p s is logged as well, if non-Null. - */ - void logProgress(const TQString &s, int p); - - /** - * Emitted once the user information has been read and - * the HotSync is really ready to go. - */ - void deviceReady( KPilotLink * ); - - -public slots: - /** - * Release all resources, including the master pilot socket, - * timers, etc. - */ - virtual void close() = 0; - - /** - * 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. - */ - virtual void reset() = 0; - - /** Tickle the underlying device exactly once. */ - virtual bool tickle() = 0; - -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. - */ - TQString fPilotPath; - - /** - * Start tickling the Handheld (every few seconds). This - * lasts until @p timeout seconds have passed (or forever - * if @p timeout is zero). - * - * @note Do not call startTickle() twice with no intervening - * stopTickle(). - */ - void startTickle(unsigned int timeout=0); - - /** - * Stop tickling the Handheld. This may block for some - * time (less than a second) to allow the tickle thread - * to finish. - */ - void stopTickle(); - - /** - * Install a single file onto the device link. Full pathname - * @p f is used; in addition, if @p deleteFile is true remove - * the source file. Returns @c true if the install succeeded. - */ - virtual bool installFile( const TQString &f, const bool deleteFile ) = 0; - - /** - * 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. - * - * @return -1 on error - * @note the default implementation returns 0 - */ - virtual int openConduit(); - - /** - * Returns a file handle for raw operations. Not recommended. - * On links with no physical device backing, returns -1. - * - * @note the default implementation returns -1 - */ - virtual int pilotSocket() const; - - /** - * Actually write an entry to the device link. The message - * @p s must be guaranteed non-empty. - */ - virtual void addSyncLogEntryImpl( const TQString &s ) = 0; - - /** - * User information structure. Should be filled in when a sync - * starts, so that conduits can use the information. - */ - KPilotUser *fPilotUser; - - /** - * System information about the device. Filled in when the - * sync starts. Non-device links need to fake something. - */ - KPilotSysInfo *fPilotSysInfo; - - -private: - bool fTickleDone; - TQThread *fTickleThread; - -} ; - -#endif |