| 1 |
**************************************************************************** |
| 2 |
* BIG FAT WARNING: * |
| 3 |
* Media Device Framework is outdated and is going to be removed as soon as * |
| 4 |
* we rewrite MtpCollection and AudioCdColleciton not to use it anymore. * |
| 5 |
**************************************************************************** |
| 6 |
|
| 7 |
Media Device Framework |
| 8 |
====================== |
| 9 |
|
| 10 |
1. Solid Interface |
| 11 |
|
| 12 |
Solid is KDE's hardware detection library, and Amarok uses it to detect |
| 13 |
all of the devices that it knows how to interface with. It does this |
| 14 |
through two classes: |
| 15 |
|
| 16 |
MediaDeviceCache(singleton) - Talks directly to Solid, gets list of all |
| 17 |
present media devices and external hard drives, even if Amarok does not |
| 18 |
support them. |
| 19 |
|
| 20 |
MediaDeviceMonitor(singleton) - Talks to the MDC to see what devices are |
| 21 |
available. Keeps track of the kind of devices that Amarok supports. |
| 22 |
It does this by receiving and caching a single ConnectionAssistant |
| 23 |
object from the MediaDeviceCollectionFactory of the particular device |
| 24 |
type, so that as devices are detected, they can be tested for |
| 25 |
compatibility with Amarok. |
| 26 |
|
| 27 |
2. Collection/Metadata |
| 28 |
|
| 29 |
Music-related data in Amarok is handled in Collections, themselves |
| 30 |
consisting of metadata such as Tracks, Artists etc. The base classes |
| 31 |
to set up collections are abstract, and several classes which provide |
| 32 |
more media-device-specific methods are available to be subclassed. It |
| 33 |
is some of these classes that must be subclassed to add support in |
| 34 |
Amarok for a device. The heart of it all is MediaDeviceHandler, and |
| 35 |
this class will be discussed in depth. |
| 36 |
|
| 37 |
NNTS = No Need To Subclass |
| 38 |
|
| 39 |
2.1 Connection |
| 40 |
|
| 41 |
ConnectionAssistant - Knows how to identify that a particular device |
| 42 |
matches the type of this CA. Can also create MediaDeviceInfo. |
| 43 |
|
| 44 |
MediaDeviceInfo - Contains the device-specific information pertinent to |
| 45 |
connection, such as mountpoint. |
| 46 |
|
| 47 |
2.2 Factory/Collection |
| 48 |
|
| 49 |
MediaDeviceCollectionFactory(NNTS) - Creates |
| 50 |
MediaDeviceCollections. Provides ConnectionAssistant to register the |
| 51 |
appropriate device type with the MDM. |
| 52 |
|
| 53 |
MediaDeviceCollection - Given a MediaDeviceInfo object, connects to the |
| 54 |
device described by creating a MediaDeviceHandler. Provides a few |
| 55 |
other rudimentary functions. |
| 56 |
|
| 57 |
MediaDeviceCollectionLocation(NNTS) - Receives/sends orders to add |
| 58 |
tracks to Collection, remove them, copy them. move them. Forwards the |
| 59 |
low-level work (the actual copying/deleting etc.) to the |
| 60 |
MediaDeviceHandler. |
| 61 |
|
| 62 |
MediaDeviceMeta*(NNTS) - The actual metadata a Collection consists of: |
| 63 |
Track, Album, Artist, Genre, Composer. No need to reimplement these, |
| 64 |
as they are standard across all devices, and the interactions |
| 65 |
concerning them are dealt with in the MediaDeviceHandler. |
| 66 |
|
| 67 |
2.3 Handler and Capabilities |
| 68 |
|
| 69 |
2.3.1 Handler |
| 70 |
|
| 71 |
MediaDeviceHandler - This is it. This is the beast that knows how to |
| 72 |
do all the low-level tasks specific to a given device: connection, |
| 73 |
parsing metadata, copying, deletion, changing of metadata, battery%, |
| 74 |
device capacity, the whole lot of it. Since it is responsible for so |
| 75 |
many pieces, and since these pieces vary greatly from device to device, |
| 76 |
it actually relies on Capability-based classes that each know how to do |
| 77 |
a particular job. |
| 78 |
|
| 79 |
Capabilities are similar to Java interfaces, and provide a standard |
| 80 |
way for the MediaDeviceHandler class to ask the many subclasses of |
| 81 |
MediaDeviceHandler for what they are capable of, and depending on that, |
| 82 |
will make different requests. For instance, AudioCDs cannot |
| 83 |
be written to, so they would have no use for WriteCapability, and don't |
| 84 |
have to implement it. |
| 85 |
|
| 86 |
The MediaDeviceHandler has abstracted the logic so common to several |
| 87 |
device implementations. The libraries libgpod and libmtp, for |
| 88 |
instance, are based on a struct that is a linked list of metadata, in |
| 89 |
particular tracks. The common way to parse the devices with these |
| 90 |
libraries is to walk down this linked list until all metadata has been |
| 91 |
read into the appropriate MediaDeviceMeta classes. This is exactly |
| 92 |
what the Handler does, and the only differences are the names of the |
| 93 |
linked list structs, and the functions called or member data read to |
| 94 |
retrieve this data. It is these basic function calls that are then |
| 95 |
called in the subclasses of the Capability classes, with the |
| 96 |
top-level logic already standardized and done in the main |
| 97 |
MediaDeviceHandler class. |
| 98 |
|
| 99 |
Note: To see the logic hereto referred, check the MediaDeviceHandler's |
| 100 |
calls to the Capability classes, and the order of the function calls. |
| 101 |
This helps to understand how best to map the functions of the |
| 102 |
Capability interface, to function calls or member-data access using the |
| 103 |
appropriate library. |
| 104 |
|
| 105 |
2.3.2 Capabilities |
| 106 |
|
| 107 |
ReadCapability - Maps the necessary functions to read the structs |
| 108 |
specific to the device, with the goal of parsing the entire device's |
| 109 |
metadata. Can also read the device's capacity, used and total. |
| 110 |
|
| 111 |
WriteCapability - Receives generic commands related to writing to |
| 112 |
the device: find where to copy a new track onto the device, copy the |
| 113 |
track, delete the track. Subclass this Capability also to provide a full |
| 114 |
mapping onto the functions required to set the metadata on a newly |
| 115 |
created track struct, and the higher logic of in what order to do this |
| 116 |
is handled by the main Handler class. |
| 117 |
|
| 118 |
ArtworkCapability - Optional. If the device supports artwork, this |
| 119 |
provides the interface for reading/writing that artwork. |
| 120 |
|
| 121 |
PlaylistCapability - Optional. If the device supports playlists, this |
| 122 |
provides the interface for reading/writing playlists, parsing logic is |
| 123 |
based again on a linked-list struct that is traversed in a standard |
| 124 |
fashion. The subclass of this just maps to the appropriate functions |
| 125 |
to walk the linked list. |
| 126 |
|
| 127 |
|
| 128 |
3. Appendix/Notes |
| 129 |
|
| 130 |
- At the time of writing, there isn't a full implementation of Solid on |
| 131 |
Windows or Mac, which limits support of devices mainly to Linux. Also, |
| 132 |
libraries used to interface at the low level (libgpod, libmtp) are |
| 133 |
Linux-specific. |