Amarok/Archives/MediaDevice

If you are looking for some hints for using your portable player with amaroK, then look here.

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;

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;

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;
 

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