From Amarok Wiki
If you are looking for some hints for using your portable player with amaroK, then look here.
Contents |
Writing a MediaDevice
This page contains a small HOW-TO for developers who wish to write an interface to an portable media device for amaroK.
Developers should refer to DeviceManager to be aware of signals that may be caught to aid them.
Understanding
We provide a fairly wholesome and easy way to interface to the Media Device browser. Please look at mediabrowser.cpp to understand the layouts and the way which the browser interacts with the device. The important class to look at is MediaDevice.
Before you start to hack on amaroK, please read the HACKING file for style and code guidelines.
What do you need to do?
At a minimum, all the pure virtual functions must be implemented by a media device, all items are stored in a hierarchy of MediaItems, and when items are manipulated the MediaItems must be updated accordingly.
A MediaItem is an subclass of KListViewItem, which exists in the mediadevicelist (the contents of the device). The following functions must be implemented:
public methods
virtual bool isConnected() = 0;
Returns
- true if the device is connected
virtual void addToPlaylist(MediaItem *playlist, MediaItem *after, QPtrList<MediaItem> items) = 0;
Adds particular tracks to a playlist
Parameters
- playlist parent playlist for tracks to be added to
- after insert following this item
- items tracks to add to playlist
virtual MediaItem *newPlaylist(const QString &name, MediaItem *parent, QPtrList<MediaItem> items) = 0;
Create a new playlist
Parameters
- name playlist title
- parent parent MediaItem of the new playlist
- items tracks to add to the new playlist
Returns
- the newly created playlist
virtual void addToDirectory( MediaItem *directory, QPtrList<MediaItem> items ) = 0;<br>
Move items to a directory
Parameters
- directory new parent of dropped items
- items tracks to add to the directory
virtual MediaItem *newDirectory( const QString &name, MediaItem *parent ) = 0;<br>
Create a new directory
Parameters
- name directory name
- parent parent MediaItem of the new directory
- items tracks to add to the new directory
Returns
- the newly created directory
private methods
virtual MediaItem *trackExists( const MetaBundle& bundle ) = 0;<br>
Find a particular track. This may not be worth implementing for non database driven devices, as it could be slow
Parameters
- bundle The metabundle of the requested media item
Returns
- The MediaItem of the item if found, otherwise 0
protected methods
virtual bool getCapacity( unsigned long *total, unsigned long *available ) = 0;
Get the capacity and freespace available on the device, in KB
Returns
- true if successful
virtual void lockDevice( bool ) = 0;
Lock device for exclusive access if possible
virtual void unlockDevice() = 0;
Unlock device
virtual bool openDevice( bool silent=false ) = 0;
Connect to device, and populate m_listview with MediaItems
Parameters
- silent if true, suppress error dialogs
Returns
- true if successful
virtual bool closeDevice() = 0;
Wrap up any loose ends and close the device
Returns
- true if successful
virtual void synchronizeDevice() = 0;
Write any pending changes to the device, such as database changes
virtual MediaItem *copyTrackToDevice(const MetaBundle& bundle, const PodcastInfo *info) = 0;
Copy a track to the device
Parameters
- bundle The MetaBundle of the item to transfer. Will move the item specified by bundle().url().path()
- info additional podcast metadata, if present, item is assumed to be a podcast
Returns
- If successful, the created MediaItem in the media device view, else 0
virtual int deleteItemFromDevice( MediaItem *item, bool onlyPlayed=false ) = 0;
Recursively remove MediaItem from the tracklist and the device
Parameters
- item MediaItem to remove
- onlyPlayed True if item should be deleted only if it has been played
Returns
- -1 on failure, number of files deleted otherwise
virtual void cancelTransfer() = 0;
Abort the currently active track transfer