src/MediaDevice.h

   1 // (c) 2004 Christian Muehlhaeuser <chris@chris.de>
   2 // (c) 2005 Martin Aumueller <aumuell@reserv.at>
   3 // (c) 2005 Seb Ruiz <ruiz@kde.org>
   4 // (c) 2006 T.R.Shashwath <trshash84@gmail.com>
   5 // (c) 2007 Jeff Mitchell <kde-dev@emailgoeshere.com>
   6 // See COPYING file for licensing information
   7
   8 #ifndef AMAROK_MEDIADEVICE_H
   9 #define AMAROK_MEDIADEVICE_H
  10
  11 #include "amarok_export.h"
  12 #include "amarok.h"
  13 #include "mediabrowser.h"
  14 #include "metabundle.h"
  15
  16 #include <QObject>
  17
  18 #include <kio/global.h>      //filesize_t
  19 #include <KUrl>            //stack allocated
  20
  21 class MediaDevice;
  22 class MediaItem;
  23 class TransferDialog;
  24 class MediaView;
  25
  26 /* at least the pure virtual functions have to be implemented by a media device,
  27    all items are stored in a hierarchy of MediaItems,
  28    when items are manipulated the MediaItems have to be updated accordingly */
  29
  30 class AMAROK_EXPORT MediaDevice : public QObject, public Amarok::Plugin
  31 {
  32     Q_OBJECT
  33     friend class DeviceConfigureDialog;
  34     friend class MediaBrowser;
  35     friend class MediaDeviceConfig;
  36     friend class MediaView;
  37     friend class MediaQueue;
  38     friend class TransferDialog;
  39
  40     public:
  41         enum Flags
  42         {
  43             None = 0,
  44             OnlyPlayed = 1,
  45             DeleteTrack = 2,
  46             Recursing = 4
  47         };
  48
  49         MediaDevice();
  50         virtual void init( MediaBrowser* parent );
  51         virtual ~MediaDevice();
  52
  53         MediaView *view();
  54
  55         /**
  56          * @return a KAction that will be plugged into the media device browser toolbar
  57          */
  58         virtual KAction *customAction() { return 0; }
  59
  60         virtual void rmbPressed( Q3ListViewItem *item, const QPoint &point, int ) { (void)item; (void) point; }
  61
  62         /**
  63          * @return list of filetypes playable on this device
  64          *  (empty list is interpreted as all types are good)
  65          */
  66         virtual QStringList supportedFiletypes() { return QStringList(); }
  67
  68         /**
  69          * @param bundle describes track that should be checked
  70          * @return true if the device is capable of playing the track referred to by bundle
  71          */
  72         virtual bool isPlayable( const MetaBundle &bundle );
  73
  74         /**
  75          * @param bundle describes track that should be checked
  76          * @return true if the track is in the preferred (first in list) format of the device
  77          */
  78         virtual bool isPreferredFormat( const MetaBundle &bundle );
  79
  80         /**
  81          * @return true if the device is connected
  82          */
  83         virtual bool       isConnected() = 0;
  84
  85         /**
  86          * Adds particular tracks to a playlist
  87          * @param playlist parent playlist for tracks to be added to
  88          * @param after insert following this item
  89          * @param items tracks to add to playlist
  90          */
  91         virtual void       addToPlaylist(MediaItem *playlist, MediaItem *after, QList<MediaItem*> items) { Q_UNUSED(playlist); Q_UNUSED(after); Q_UNUSED(items); }
  92
  93         /**
  94          * Create a new playlist
  95          * @param name playlist title
  96          * @param parent parent MediaItem of the new playlist
  97          * @param items tracks to add to the new playlist
  98          * @return the newly created playlist
  99          */
 100         virtual MediaItem *newPlaylist(const QString &name, MediaItem *parent, QList<MediaItem*> items) { Q_UNUSED(name); Q_UNUSED(parent); Q_UNUSED(items); return 0; }
 101
 102         /**
 103          * Move items to a directory
 104          * @param directory new parent of dropped items
 105          * @param items tracks to add to the directory
 106          */
 107         virtual void      addToDirectory( MediaItem *directory, QList<MediaItem*> items ) { Q_UNUSED(directory); Q_UNUSED(items); }
 108
 109         /**
 110          * Create a new directory
 111          * @param name directory title
 112          * @param parent parent MediaItem of the new directory
 113          * @param items tracks to add to the new directory
 114          * @return the newly created directory
 115          */
 116         virtual MediaItem *newDirectory( const QString &name, MediaItem *parent ) { Q_UNUSED(name); Q_UNUSED(parent); return 0; }
 117
 118         /**
 119          * Notify device of changed tags
 120          * @param item item to be updated
 121          * @param changed bundle containing new tags
 122          * @return the changed MediaItem
 123          */
 124         virtual MediaItem *tagsChanged( MediaItem *item, const MetaBundle &changed ) { Q_UNUSED(item); Q_UNUSED(changed); return 0; }
 125
 126         /**
 127          * Indicate whether the device has a custom transfer dialog
 128          * @return whether there is a custom dialog
 129          */
 130         virtual bool hasTransferDialog() { return false; }
 131
 132         /**
 133          * Run the transfer dialog to be used when Transfer is clicked
 134          */
 135         virtual void runTransferDialog() {}
 136
 137         /**
 138          * Get the transfer dialog, if any
 139          * @return the transfer dialog, if any, else NULL;
 140          */
 141         virtual TransferDialog *getTransferDialog() { return NULL; }
 142
 143         /**
 144          * Can be used to explicitly indicate whether a device needs manual configuration
 145          * @return whether manual configuration is needed
 146          */
 147         virtual bool needsManualConfig() { return true; }
 148
 149         virtual void addConfigElements( QWidget * /*parent*/ ) {}
 150         virtual void removeConfigElements( QWidget * /*parent*/ ) {}
 151         virtual void applyConfig() {}
 152         virtual void loadConfig();
 153
 154         QString configString( const QString &name, const QString &defValue = QString() );
 155         void setConfigString( const QString &name, const QString &value );
 156         bool configBool( const QString &name, bool defValue=false );
 157         void setConfigBool( const QString &name, bool value );
 158
 159         void         setRequireMount( const bool b ) { m_requireMount = b; }
 160         bool         hasMountPoint() { return m_hasMountPoint; }
 161         void         setDeviceType( const QString &type ) { m_type = type; }
 162         QString      type() { return m_type; }
 163         virtual bool autoConnect() { return false; }
 164         virtual bool asynchronousTransfer() { return false; }
 165         bool         isTransferring() { return m_transferring; }
 166         bool         isDeleting() { return m_deleting; }
 167         bool         isCanceled() { return m_canceled; }
 168         void         setCanceled( const bool b ) { m_canceled = b; }
 169
 170         int          progress() const;
 171         void         setProgress( const int progress, const int total = -1 /* leave total unchanged by default */ );
 172         void         hideProgress();
 173
 174
 175         /**
 176          * @return a unique identifier that is constant across sessions
 177          */
 178         QString udi() const { return m_udi; }
 179
 180         /**
 181          * @return the name for the device that should be presented to the user
 182          */
 183         QString name() const { return m_name; }
 184
 185         /**
 186          * @return the filesystem type
 187          */
 188         QString fsType() const { return m_fsType; }
 189
 190         /**
 191          * @return the device node
 192          */
 193         QString deviceNode() const { return m_deviceNode; }
 194
 195         /*
 196          * @return the device mount point (or empty if non-applicable or unknown)
 197          */
 198         QString mountPoint() const { return m_mountPoint; }
 199
 200         QString           getTransferDir() { return m_transferDir; }
 201
 202         void              setSpacesToUnderscores( bool yesno ) { m_spacesToUnderscores = yesno;
 203             setConfigBool( "spacesToUnderscores", yesno); }
 204         bool              getSpacesToUnderscores() { return m_spacesToUnderscores; }
 205
 206         void              setFirstSort( QString text ) { m_firstSort = text;
 207             setConfigString( "firstGrouping", text ); }
 208         void              setSecondSort( QString text ) { m_secondSort = text;
 209             setConfigString( "secondGrouping", text ); }
 210         void              setThirdSort( QString text ) { m_thirdSort = text;
 211             setConfigString( "thirdGrouping", text ); }
 212
 213         virtual KUrl getProxyUrl( const KUrl& /*url*/) { return KUrl(); }
 214         virtual void customClicked() { return; }
 215
 216         BundleList bundlesToSync( const QString &playlistName, const QString &sql );
 217         BundleList bundlesToSync( const QString &playlistName, const KUrl &url );
 218         void preparePlaylistForSync( const QString &playlistName, const BundleList &bundles );
 219         bool isOnOtherPlaylist( const QString &playlistToAvoid, const MetaBundle &bundle );
 220         bool isOnPlaylist( const MediaItem &playlist, const MetaBundle &bundle );
 221         bool isInBundleList( const BundleList &bundles, const MetaBundle &bundle );
 222         bool bundleMatch( const MetaBundle &b1, const MetaBundle &b2 );
 223
 224     public slots:
 225         void abortTransfer();
 226         void transferFiles();
 227         virtual void renameItem( Q3ListViewItem *item ) {(void)item; }
 228         virtual void expandItem( Q3ListViewItem *item ) {(void)item; }
 229         bool connectDevice( bool silent=false );
 230         bool disconnectDevice( bool postdisconnecthook=true );
 231         void scheduleDisconnect() { m_scheduledDisconnect = true; }
 232
 233     protected slots:
 234         void fileTransferred( KIO::Job *job );
 235         void fileTransferFinished();
 236
 237     private:
 238         int  sysCall(const QString & command);
 239         int  runPreConnectCommand();
 240         int  runPostDisconnectCommand();
 241         QString replaceVariables( const QString &cmd ); // replace %m with mount point and %d with device node
 242
 243         void setUid( const QString &udi ) { m_udi = udi; }
 244
 245         /**
 246          * Find a particular track
 247          * @param bundle The metabundle of the requested media item
 248          * @return The MediaItem of the item if found, otherwise NULL
 249          * @note This may not be worth implementing for non database driven devices, as it could be slow
 250          */
 251         virtual MediaItem *trackExists( const MetaBundle& bundle ) = 0;
 252
 253     protected:
 254         /**
 255          * Get the capacity and freespace available on the device, in bytes
 256          * @return true if successful
 257          */
 258         virtual bool getCapacity( KIO::filesize_t *total, KIO::filesize_t *available ) { Q_UNUSED(total); Q_UNUSED(available); return false; }
 259
 260         /**
 261          * Lock device for exclusive access if possible
 262          */
 263         virtual bool lockDevice( bool tryOnly = false ) = 0;
 264
 265         /**
 266          * Unlock device
 267          */
 268         virtual void unlockDevice() = 0;
 269
 270         /**
 271          * Connect to device, and populate m_view with MediaItems
 272          * @return true if successful
 273          */
 274         virtual bool openDevice( bool silent=false ) = 0;
 275
 276         /**
 277          * Wrap up any loose ends and close the device
 278          * @return true if successful
 279          */
 280         virtual bool closeDevice() = 0;
 281
 282         /**
 283          * Write any pending changes to the device, such as database changes
 284          */
 285         virtual void synchronizeDevice() = 0;
 286
 287         /**
 288          * Copy a track to the device
 289          * @param bundle The MetaBundle of the item to transfer. Will move the item specified by bundle().url().path()
 290          * @return If successful, the created MediaItem in the media device view, else 0
 291          */
 292         virtual MediaItem *copyTrackToDevice(const MetaBundle& bundle) = 0;
 293
 294         /**
 295          * Copy track from device to computer
 296          * @param item The MediaItem of the track to transfer.
 297          * @param url The URL to transfer the track to.
 298          * @return The MediaItem transfered.
 299          */
 300         virtual void copyTrackFromDevice(MediaItem *item);
 301
 302         /**
 303          * Recursively remove MediaItem from the tracklist and the device
 304          * @param item MediaItem to remove
 305          * @param onlyPlayed True if item should be deleted only if it has been played
 306          * @return -1 on failure, number of files deleted otherwise
 307          */
 308         virtual int deleteItemFromDevice( MediaItem *item, int flags=DeleteTrack ) = 0;
 309
 310         /**
 311          * Abort the currently active track transfer
 312          */
 313         virtual void cancelTransfer() { /* often checking m_cancel is enough */ }
 314
 315         virtual void updateRootItems();
 316
 317         virtual bool isSpecialItem( MediaItem *item );
 318
 319         int deleteFromDevice( MediaItem *item=0, int flags=DeleteTrack );
 320
 321         void purgeEmptyItems( MediaItem *root=0 );
 322         void syncStatsFromDevice( MediaItem *root=0 );
 323         void syncStatsToDevice( MediaItem *root=0 );
 324
 325         bool kioCopyTrack( const KUrl &src, const KUrl &dst );
 326
 327         QString     m_name;
 328
 329         bool        m_hasMountPoint;
 330
 331         QString     m_preconnectcmd;
 332         QString     m_postdisconnectcmd;
 333         bool        m_autoDeletePodcasts;
 334         bool        m_syncStats;
 335
 336         bool        m_transcode;
 337         bool        m_transcodeAlways;
 338         bool        m_transcodeRemove;
 339
 340         K3ShellProcess   *sysProc;
 341         MediaBrowser    *m_parent;
 342         MediaView       *m_view;
 343         QString          m_transferDir;
 344         QString          m_firstSort;
 345         QString          m_secondSort;
 346         QString          m_thirdSort;
 347         QString          m_udi;
 348         QString          m_deviceNode;
 349         QString          m_mountPoint;
 350         QString          m_fsType;
 351         bool             m_wait;
 352         bool             m_waitForDeletion;
 353         bool             m_copyFailed;
 354         bool             m_requireMount;
 355         bool             m_canceled;
 356         bool             m_transferring;
 357         bool             m_deleting;
 358         bool             m_deferredDisconnect;
 359         bool             m_scheduledDisconnect;
 360         bool             m_runDisconnectHook;
 361         bool             m_spacesToUnderscores;
 362         bool             m_transfer;
 363         bool             m_configure;
 364         bool             m_customButton;
 365
 366         QString          m_type;
 367
 368         // root listview items
 369         MediaItem *m_playlistItem;
 370         MediaItem *m_podcastItem;
 371         // items not on the master playlist and not on the podcast playlist are not visible on the ipod
 372         MediaItem *m_invisibleItem;
 373         // items in the database for which the file is missing
 374         MediaItem *m_staleItem;
 375         // files without database entry
 376         MediaItem *m_orphanedItem;
 377
 378         // stow away all items below m_rootItems when device is not current
 379         QList<Q3ListViewItem*> m_rootItems;
 380 };
 381
 382
 383 #endif /* AMAROK_MEDIADEVICE_H */