summaryrefslogtreecommitdiffstats
path: root/kmobile/kmobiledevice.h
diff options
context:
space:
mode:
Diffstat (limited to 'kmobile/kmobiledevice.h')
-rw-r--r--kmobile/kmobiledevice.h504
1 files changed, 504 insertions, 0 deletions
diff --git a/kmobile/kmobiledevice.h b/kmobile/kmobiledevice.h
new file mode 100644
index 000000000..5fbcad6d2
--- /dev/null
+++ b/kmobile/kmobiledevice.h
@@ -0,0 +1,504 @@
+/* This file is part of the KDE kmobile library.
+ Copyright (C) 2003 Helge Deller <deller@kde.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License version 2 as published by the Free Software Foundation.
+
+ This library 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
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+
+*/
+
+#ifndef LIB_KMOBILEDEVICE_H
+#define LIB_KMOBILEDEVICE_H
+
+#include <qstring.h>
+#include <qstringlist.h>
+#include <qmutex.h>
+
+#include <kdepimmacros.h>
+#include <klibloader.h>
+
+#include <kabc/addressee.h>
+#include <kabc/addresseelist.h>
+
+#include <kio/global.h>
+#include <kio/authinfo.h>
+
+#include <libkcal/event.h>
+
+class KConfig;
+
+#define KMOBILE_MIMETYPE_DEVICE "kdedevice/mobiledevice"
+#define KMOBILE_MIMETYPE_DEVICE_KONQUEROR(name) QString("kdedevice/kmobile_%1").arg(name)
+#define KMOBILE_MIMETYPE_INODE "inode/"
+#define KMOBILE_ICON_UNKNOWN "mobile_unknown"
+
+/**
+ * @short Represents the base class for dynamically loaded mobile device drivers.
+ *
+ * KMobileDevice is the base class for all hardware device drivers.
+ * Every derived class has to add additional functionality.
+ *
+ * For a KMobileSomeDevice driver you have to write the following code:
+ * <pre>
+ * K_EXPORT_COMPONENT_FACTORY( libkmobile_somedevice, KMobileSomeDevice() );
+ * QObject *KMobileSomeDevice::createObject( QObject *parent, const char *name,
+ * const char *, const QStringList &args )
+ * {
+ * return new KMobileSomeDevice( parent, name, args );
+ * }
+ * </pre>
+ *
+ * @see KLibFactory
+ * @author Helge Deller <deller@kde.org>
+ */
+
+class KDE_EXPORT KMobileDevice : public KLibFactory
+{
+Q_OBJECT
+ friend class KMobileView;
+
+public:
+ /**
+ * Construct a new KMobileDevice.
+ *
+ * @param obj The parent object. This is usually 0.
+ * @param name The object name. For session management and window management to work.
+ * @param args Additional commandline parameters - the first entry has the config file name.
+ */
+ KMobileDevice(QObject *obj, const char *name, const QStringList &args );
+ virtual ~KMobileDevice();
+
+
+ /**
+ * Connect to the device.
+ *
+ * @param parent The parent widget. It will be used as parent for message boxes.
+ */
+ virtual bool connectDevice( QWidget *parent = 0 ) = 0;
+
+ /**
+ * Disconnect from the device.
+ *
+ * @param parent The parent widget. It will be used as parent for message boxes.
+ */
+ virtual bool disconnectDevice( QWidget *parent = 0 ) = 0;
+
+ /**
+ * Returns true, if the device is currently connected and the link is online.
+ */
+ virtual bool connected();
+
+ /**
+ * Returns the classname, to which the device belongs. Examples are e.g.
+ * "Nokia mobile phone", "MP3 Player", "Handspring Organizer"
+ */
+ virtual QString deviceClassName() const;
+
+ /**
+ * Returns the real devices name, e.g. "Nokia 6310" or "Rio MP3 Player"
+ */
+ virtual QString deviceName() const;
+
+ /**
+ * Returns the hardware revision of the devices, e.g. "Revision 1.2"
+ */
+ virtual QString revision() const;
+
+ /**
+ * Returns an unique ID for the device, e.g. IMEI number on phones, or serial number.
+ * The returned String is used to have a unique identification for syncronisation.
+ */
+ virtual QString deviceUniqueID() = 0;
+
+ /**
+ * Returns true, if the device is connected via a slow connection.
+ * Good examples for slow connections are serial or infrared ports.
+ */
+ virtual bool isSlowDevice() const;
+
+ /**
+ * Returns true, if this is a read-only device.
+ */
+ virtual bool isReadOnly() const;
+
+ /**
+ * Pop-up a device-specific configuration dialog.
+ *
+ * @param parent The parent widget. It will be used as parent for the configuration dialog.
+ */
+ virtual bool configDialog(QWidget *parent);
+
+ // The ClassType may be used e.g. to select an suitable icon
+ enum ClassType {
+ Unclassified = 0,
+ Phone = 1,
+ Organizer = 2,
+ Camera = 3,
+ MusicPlayer = 4, // e.g. MP3Players, CDPlayers
+ LastClassType = MusicPlayer
+ };
+ enum ClassType classType() const;
+
+ // you may provide your own icon() implementation to display
+ // an appropriate Pixmap (e.g. a Palm Pilot or a Zaurus image).
+ virtual QString iconFileName() const;
+
+ // the default Icon set
+ static QString defaultIconFileName( ClassType ct = Unclassified );
+ static QString defaultClassName( ClassType ct = Unclassified );
+
+ // The capabilities of this device (bitmapped value)
+ enum Capabilities {
+ hasNothing = 0, // not supported
+ hasAddressBook = 1, // mobile phones, organizers, ...
+ hasCalendar = 2, // organizers, mobile phones, ...
+ hasNotes = 4, // organizers, mobile phones, ...
+ hasFileStorage = 8, // organizers, handhelds, mp3-player, ...
+ hasAnyCapability = 0xffff // used to select devices independent of the capatibilities
+ };
+ int capabilities() const;
+ const QString nameForCap(int cap) const;
+
+ // returns an error string for the given error code
+ // See KIO::buildErrorString()
+ QString buildErrorString(KIO::Error err, const QString &errorText) const;
+
+public:
+ /*
+ * Addressbook / Phonebook support
+ */
+ virtual int numAddresses();
+ virtual int readAddress( int index, KABC::Addressee &adr );
+ virtual int storeAddress( int index, const KABC::Addressee &adr, bool append = false );
+
+ /*
+ * Calendar support
+ */
+ virtual int numCalendarEntries();
+ virtual int readCalendarEntry( int index, KCal::Event &entry );
+ virtual int storeCalendarEntry( int index, const KCal::Event &entry );
+
+ /*
+ * Notes support
+ */
+ virtual int numNotes();
+ virtual int readNote( int index, QString &note );
+ virtual int storeNote( int index, const QString &note );
+
+
+
+ /*
+ **********************
+ * FILE STORAGE SUPPORT
+ **********************
+ * mostly compatible to the kioslave base class <kio/slavebase.h>
+ */
+
+ /**
+ * helper functions for the kmobile device drivers
+ */
+ void createDirEntry(KIO::UDSEntry& entry, const QString& name,
+ const QString& url, const QString& mime) const;
+ void createFileEntry(KIO::UDSEntry& entry, const QString& name,
+ const QString& url, const QString& mime,
+ const unsigned long size = 0) const;
+ /**
+ * Lists the contents of @p path.
+ * The slave should emit ERR_CANNOT_ENTER_DIRECTORY if it doesn't exist,
+ * if we don't have enough permissions, or if it is a file
+ * It should also emit @ref #totalFiles as soon as it knows how many
+ * files it will list.
+ */
+ virtual void listDir( const QString &url );
+
+ /**
+ * Create a directory
+ * @param path path to the directory to create
+ * @param permissions the permissions to set after creating the directory
+ * (-1 if no permissions to be set)
+ * The slave emits ERR_COULD_NOT_MKDIR if failure.
+ */
+ virtual void mkdir( const QString &url, int permissions );
+
+ /**
+ * Rename @p oldname into @p newname.
+ * If the slave returns an error ERR_UNSUPPORTED_ACTION, the job will
+ * ask for copy + del instead.
+ * @param src where to move the file from
+ * @param dest where to move the file to
+ * @param overwrite if true, any existing file will be overwritten
+ */
+ virtual void rename( const QString &src, const QString &dest, bool overwrite );
+
+ /**
+ * Creates a symbolic link named @p dest, pointing to @p target, which
+ * may be a relative or an absolute path.
+ * @param target The string that will become the "target" of the link (can be relative)
+ * @param dest The symlink to create.
+ * @param overwrite whether to automatically overwrite if the dest exists
+ */
+ virtual void symlink( const QString &target, const QString &dest, bool overwrite );
+
+ /**
+ * Delete a file or directory.
+ * @param path file/directory to delete
+ * @param isfile if true, a file should be deleted.
+ * if false, a directory should be deleted.
+ */
+ virtual void del( const QString &url, bool isfile);
+
+ /**
+ * Finds all details for one file or directory.
+ * The information returned is the same as what @ref #listDir returns,
+ * but only for one file or directory.
+ */
+ virtual void stat( const QString &url );
+
+ /**
+ * Change permissions on @p path
+ * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_CHMOD
+ */
+ virtual void chmod( const QString &url, int permissions );
+
+ /**
+ * get, aka read.
+ * @param url the full url for this request. Host, port and user of the URL
+ * can be assumed to be the same as in the last setHost() call.
+ * The slave emits the data through @ref #data
+ */
+ virtual void get( const QString &url );
+
+ /**
+ * put, aka write.
+ * @param path where to write the file (decoded)
+ * @param permissions may be -1. In this case no special permission mode is set.
+ * @param overwrite if true, any existing file will be overwritten.
+ * If the file indeed already exists, the slave should NOT apply the
+ * permissions change to it.
+ * @param resume
+ */
+ virtual void put( const QString &url, int permissions, bool overwrite, bool resume );
+
+ /**
+ * Finds mimetype for one file or directory.
+ *
+ * This method should either emit 'mimeType' or it
+ * should send a block of data big enough to be able
+ * to determine the mimetype.
+ *
+ * If the slave doesn't reimplement it, a @ref #get will
+ * be issued, i.e. the whole file will be downloaded before
+ * determining the mimetype on it - this is obviously not a
+ * good thing in most cases.
+ */
+ virtual void mimetype( const QString &url );
+
+ /**
+ * Used for any command that is specific to this slave (protocol)
+ * Examples are : HTTP POST, mount and unmount (kio_file)
+ *
+ * @param data packed data; the meaning is completely dependent on the
+ * slave, but usually starts with an int for the command number.
+ * Document your slave's commands, at least in its header file.
+ */
+ virtual void special( const QByteArray & );
+
+signals:
+ /**
+ * Call this from stat() to express details about an object, the
+ * UDSEntry customarily contains the atoms describing file name, size,
+ * mimetype, etc.
+ * @param _entry The UDSEntry containing all of the object attributes.
+ */
+ void statEntry( const KIO::UDSEntry &_entry );
+
+ /**
+ * internal function to be called by the slave.
+ * It collects entries and emits them via listEntries
+ * when enough of them are there or a certain time
+ * frame exceeded (to make sure the app gets some
+ * items in time but not too many items one by one
+ * as this will cause a drastic performance penalty)
+ * @param ready set to true after emitting all items. _entry is not
+ * used in this case
+ */
+ void listEntry( const KIO::UDSEntry& _entry, bool ready);
+
+ /**
+ * Internal function to transmit meta data to the application.
+ */
+ void sendMetaData();
+
+ /**
+ * Prompt the user for Authorization info (login & password).
+ *
+ * Use this function to request authorization information from
+ * the end user. You can also pass an error message which explains
+ * why a previous authorization attempt failed. Here is a very
+ * simple example:
+ *
+ * <pre>
+ * KIO::AuthInfo authInfo;
+ * if ( openPassDlg( authInfo ) )
+ * {
+ * kdDebug() << QString::fromLatin1("User: ")
+ * << authInfo.username << endl;
+ * kdDebug() << QString::fromLatin1("Password: ")
+ * << QString::fromLatin1("Not displayed here!") << endl;
+ * }
+ * </pre>
+ *
+ * You can also preset some values like the username, caption or
+ * comment as follows:
+ *
+ * <pre>
+ * KIO::AuthInfo authInfo;
+ * authInfo.caption= "Acme Password Dialog";
+ * authInfo.username= "Wile E. Coyote";
+ * QString errorMsg = "You entered an incorrect password.";
+ * if ( openPassDlg( authInfo, errorMsg ) )
+ * {
+ * kdDebug() << QString::fromLatin1("User: ")
+ * << authInfo.username << endl;
+ * kdDebug() << QString::fromLatin1("Password: ")
+ * << QString::fromLatin1("Not displayed here!") << endl;
+ * }
+ * </pre>
+ *
+ * NOTE: A call to this function can fail and return @p false,
+ * if the UIServer could not be started for whatever reason.
+ *
+ * @param info See @ref AuthInfo.
+ * @param errorMsg Error message to show
+ * @return @p TRUE if user clicks on "OK", @p FALSE otherwsie.
+ * @since 3.1
+ */
+ bool openPassDlg( KIO::AuthInfo& info, const QString &errorMsg );
+
+ /**
+ * Call this in @ref #mimetype, when you know the mimetype.
+ * See @ref #mimetype about other ways to implement it.
+ */
+ void mimeType( const QString &_type );
+
+ /**
+ * Call to signal an error.
+ * This also finishes the job, no need to call finished.
+ *
+ * If the Error code is KIO::ERR_SLAVE_DEFINED then the
+ * _text should contain the complete translated text of
+ * of the error message. This message will be displayed
+ * in an KTextBrowser which allows rich text complete
+ * with hyper links. Email links will call the default
+ * mailer, "exec:/command arg1 arg2" will be forked and
+ * all other links will call the default browser.
+ *
+ * @see KIO::Error
+ * @see KTextBrowser
+ * @param _errid the error code from KIO::Error
+ * @param _text the rich text error message
+ */
+ void error( int _errid, const QString &_text );
+
+ /**
+ * Call to signal a warning, to be displayed in a dialog box.
+ */
+ void warning( const QString &msg );
+
+ /**
+ * Call to signal a message, to be displayed if the application wants to,
+ * for instance in a status bar. Usual examples are "connecting to host xyz", etc.
+ */
+ void infoMessage( const QString &msg );
+
+ /**
+ * Call to signal successful completion of any command
+ * (besides openConnection and closeConnection)
+ */
+ void finished();
+
+
+ enum MessageBoxType { QuestionYesNo = 1, WarningYesNo = 2, WarningContinueCancel = 3,
+ WarningYesNoCancel = 4, Information = 5, SSLMessageBox = 6 };
+
+ /**
+ * Call this to show a message box from the slave (it will in fact be handled
+ * by kio_uiserver, so that the progress info dialog for the slave is hidden
+ * while this message box is shown)
+ * @param type type of message box: QuestionYesNo, WarningYesNo, WarningContinueCancel...
+ * @param text Message string. May contain newlines.
+ * @param caption Message box title.
+ * @param buttonYes The text for the first button.
+ * The default is i18n("&Yes").
+ * @param buttonNo The text for the second button.
+ * The default is i18n("&No").
+ * Note: for ContinueCancel, buttonYes is the continue button and buttonNo is unused.
+ * and for Information, none is used.
+ * @return a button code, as defined in KMessageBox, or 0 on communication error.
+ */
+ int messageBox( MessageBoxType type, const QString &text,
+ const QString &caption = QString::null,
+ const QString &buttonYes = QString::null,
+ const QString &buttonNo = QString::null );
+
+ /**
+ * Call this in @ref #get and @ref #copy, to give the total size
+ * of the file
+ * Call in @ref listDir too, when you know the total number of items.
+ */
+ void totalSize( KIO::filesize_t _bytes );
+ /**
+ * Call this during @ref #get and @ref #copy, once in a while,
+ * to give some info about the current state.
+ * Don't emit it in @ref #listDir, @ref #listEntries speaks for itself.
+ */
+ void processedSize( KIO::filesize_t _bytes );
+
+
+signals:
+ void connectionChanged( bool conn_established );
+
+protected:
+ // only available to sub-classed device drivers:
+ void setClassType( enum ClassType ct );
+ void setCapabilities( int caps );
+ KConfig *config() const { return m_config; };
+ QString configFileName() const { return m_configFileName; };
+
+
+ /**
+ * Lock/Unlock serial ports and other devices
+ * @param device Name of a device port (e.g. /dev/ttyS1, ttyS1, /dev/ircomm0)
+ * Returns true, if device could be locked or unlocked
+ */
+ bool lockDevice(const QString &device, QString &err_reason);
+ bool unlockDevice(const QString &device);
+
+protected:
+ QMutex m_mutex; // mutex to syncronize DCOP accesses to this device
+ QString m_configFileName;
+ KConfig *m_config; // this is where this device should store it's configuration
+ enum ClassType m_classType;
+ QString m_deviceClassName; // e.g. "Nokia mobile phone", "MP3 Player", "Handspring Organizer"
+ QString m_deviceName; // e.g. "Nokia 6310", "Opie"
+ QString m_deviceRevision; // e.g. "Revision 1.2" or "n/a"
+ QString m_connectionName; // e.g. "IRDA", "USB", "Cable", "gnokii", "gammu", ...
+ int m_caps; // see enum Capabilities
+ bool m_connected;
+
+private:
+ class KMobileDevicePrivate *d;
+};
+
+#endif /* LIB_KMOBILEDEVICE_H */
+