You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
507 lines
18 KiB
507 lines
18 KiB
/* 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 <tqstring.h>
|
|
#include <tqstringlist.h>
|
|
#include <tqmutex.h>
|
|
|
|
#include <tdepimmacros.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_KONTQUEROR(name) TQString("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() );
|
|
* TQObject *KMobileSomeDevice::createObject( TQObject *parent, const char *name,
|
|
* const char *, const TQStringList &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(TQObject *obj, const char *name, const TQStringList &args );
|
|
virtual ~KMobileDevice();
|
|
|
|
|
|
/**
|
|
* Connect to the device.
|
|
*
|
|
* @param parent The parent widget. It will be used as parent for message boxes.
|
|
*/
|
|
virtual bool connectDevice( TQWidget *parent = 0 ) = 0;
|
|
|
|
/**
|
|
* Disconnect from the device.
|
|
*
|
|
* @param parent The parent widget. It will be used as parent for message boxes.
|
|
*/
|
|
virtual bool disconnectDevice( TQWidget *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 TQString deviceClassName() const;
|
|
|
|
/**
|
|
* Returns the real devices name, e.g. "Nokia 6310" or "Rio MP3 Player"
|
|
*/
|
|
virtual TQString deviceName() const;
|
|
|
|
/**
|
|
* Returns the hardware revision of the devices, e.g. "Revision 1.2"
|
|
*/
|
|
virtual TQString 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 TQString 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(TQWidget *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 TQString iconFileName() const;
|
|
|
|
// the default Icon set
|
|
static TQString defaultIconFileName( ClassType ct = Unclassified );
|
|
static TQString 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 TQString nameForCap(int cap) const;
|
|
|
|
// returns an error string for the given error code
|
|
// See KIO::buildErrorString()
|
|
TQString buildErrorString(KIO::Error err, const TQString &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, TQString ¬e );
|
|
virtual int storeNote( int index, const TQString ¬e );
|
|
|
|
|
|
|
|
/*
|
|
**********************
|
|
* 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 TQString& name,
|
|
const TQString& url, const TQString& mime) const;
|
|
void createFileEntry(KIO::UDSEntry& entry, const TQString& name,
|
|
const TQString& url, const TQString& 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 TQString &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 TQString &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 TQString &src, const TQString &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 TQString &target, const TQString &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 TQString &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 TQString &url );
|
|
|
|
/**
|
|
* Change permissions on @p path
|
|
* The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_CHMOD
|
|
*/
|
|
virtual void chmod( const TQString &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 TQString &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 TQString &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 TQString &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 TQByteArray & );
|
|
|
|
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() << TQString::fromLatin1("User: ")
|
|
* << authInfo.username << endl;
|
|
* kdDebug() << TQString::fromLatin1("Password: ")
|
|
* << TQString::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";
|
|
* TQString errorMsg = "You entered an incorrect password.";
|
|
* if ( openPassDlg( authInfo, errorMsg ) )
|
|
* {
|
|
* kdDebug() << TQString::fromLatin1("User: ")
|
|
* << authInfo.username << endl;
|
|
* kdDebug() << TQString::fromLatin1("Password: ")
|
|
* << TQString::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 TQString &errorMsg );
|
|
|
|
/**
|
|
* Call this in @ref #mimetype, when you know the mimetype.
|
|
* See @ref #mimetype about other ways to implement it.
|
|
*/
|
|
void mimeType( const TQString &_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 TQString &_text );
|
|
|
|
/**
|
|
* Call to signal a warning, to be displayed in a dialog box.
|
|
*/
|
|
void warning( const TQString &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 TQString &msg );
|
|
|
|
/**
|
|
* Call to signal successful completion of any command
|
|
* (besides openConnection and closeConnection)
|
|
*/
|
|
void finished();
|
|
|
|
#ifndef Q_MOC_RUN
|
|
enum MessageBoxType { QuestionYesNo = 1, WarningYesNo = 2, WarningContinueCancel = 3,
|
|
WarningYesNoCancel = 4, Information = 5, SSLMessageBox = 6 };
|
|
#endif // Q_MOC_RUN
|
|
|
|
/**
|
|
* 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 TQString &text,
|
|
const TQString &caption = TQString(),
|
|
const TQString &buttonYes = TQString(),
|
|
const TQString &buttonNo = TQString() );
|
|
|
|
/**
|
|
* 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; };
|
|
TQString 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 TQString &device, TQString &err_reason);
|
|
bool unlockDevice(const TQString &device);
|
|
|
|
protected:
|
|
TQMutex m_mutex; // mutex to syncronize DCOP accesses to this device
|
|
TQString m_configFileName;
|
|
KConfig *m_config; // this is where this device should store it's configuration
|
|
enum ClassType m_classType;
|
|
TQString m_deviceClassName; // e.g. "Nokia mobile phone", "MP3 Player", "Handspring Organizer"
|
|
TQString m_deviceName; // e.g. "Nokia 6310", "Opie"
|
|
TQString m_deviceRevision; // e.g. "Revision 1.2" or "n/a"
|
|
TQString 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 */
|
|
|