Warning, /multimedia/amarok/HACKING/OUTDATED-MediaDeviceFramework is written in an unsupported language. File is not indexed.
0001 **************************************************************************** 0002 * BIG FAT WARNING: * 0003 * Media Device Framework is outdated and is going to be removed as soon as * 0004 * we rewrite MtpCollection and AudioCdColleciton not to use it anymore. * 0005 **************************************************************************** 0006 0007 Media Device Framework 0008 ====================== 0009 0010 1. Solid Interface 0011 0012 Solid is KDE's hardware detection library, and Amarok uses it to detect 0013 all of the devices that it knows how to interface with. It does this 0014 through two classes: 0015 0016 MediaDeviceCache(singleton) - Talks directly to Solid, gets list of all 0017 present media devices and external hard drives, even if Amarok does not 0018 support them. 0019 0020 MediaDeviceMonitor(singleton) - Talks to the MDC to see what devices are 0021 available. Keeps track of the kind of devices that Amarok supports. 0022 It does this by receiving and caching a single ConnectionAssistant 0023 object from the MediaDeviceCollectionFactory of the particular device 0024 type, so that as devices are detected, they can be tested for 0025 compatibility with Amarok. 0026 0027 2. Collection/Metadata 0028 0029 Music-related data in Amarok is handled in Collections, themselves 0030 consisting of metadata such as Tracks, Artists etc. The base classes 0031 to set up collections are abstract, and several classes which provide 0032 more media-device-specific methods are available to be subclassed. It 0033 is some of these classes that must be subclassed to add support in 0034 Amarok for a device. The heart of it all is MediaDeviceHandler, and 0035 this class will be discussed in depth. 0036 0037 NNTS = No Need To Subclass 0038 0039 2.1 Connection 0040 0041 ConnectionAssistant - Knows how to identify that a particular device 0042 matches the type of this CA. Can also create MediaDeviceInfo. 0043 0044 MediaDeviceInfo - Contains the device-specific information pertinent to 0045 connection, such as mountpoint. 0046 0047 2.2 Factory/Collection 0048 0049 MediaDeviceCollectionFactory(NNTS) - Creates 0050 MediaDeviceCollections. Provides ConnectionAssistant to register the 0051 appropriate device type with the MDM. 0052 0053 MediaDeviceCollection - Given a MediaDeviceInfo object, connects to the 0054 device described by creating a MediaDeviceHandler. Provides a few 0055 other rudimentary functions. 0056 0057 MediaDeviceCollectionLocation(NNTS) - Receives/sends orders to add 0058 tracks to Collection, remove them, copy them. move them. Forwards the 0059 low-level work (the actual copying/deleting etc.) to the 0060 MediaDeviceHandler. 0061 0062 MediaDeviceMeta*(NNTS) - The actual metadata a Collection consists of: 0063 Track, Album, Artist, Genre, Composer. No need to reimplement these, 0064 as they are standard across all devices, and the interactions 0065 concerning them are dealt with in the MediaDeviceHandler. 0066 0067 2.3 Handler and Capabilities 0068 0069 2.3.1 Handler 0070 0071 MediaDeviceHandler - This is it. This is the beast that knows how to 0072 do all the low-level tasks specific to a given device: connection, 0073 parsing metadata, copying, deletion, changing of metadata, battery%, 0074 device capacity, the whole lot of it. Since it is responsible for so 0075 many pieces, and since these pieces vary greatly from device to device, 0076 it actually relies on Capability-based classes that each know how to do 0077 a particular job. 0078 0079 Capabilities are similar to Java interfaces, and provide a standard 0080 way for the MediaDeviceHandler class to ask the many subclasses of 0081 MediaDeviceHandler for what they are capable of, and depending on that, 0082 will make different requests. For instance, AudioCDs cannot 0083 be written to, so they would have no use for WriteCapability, and don't 0084 have to implement it. 0085 0086 The MediaDeviceHandler has abstracted the logic so common to several 0087 device implementations. The libraries libgpod and libmtp, for 0088 instance, are based on a struct that is a linked list of metadata, in 0089 particular tracks. The common way to parse the devices with these 0090 libraries is to walk down this linked list until all metadata has been 0091 read into the appropriate MediaDeviceMeta classes. This is exactly 0092 what the Handler does, and the only differences are the names of the 0093 linked list structs, and the functions called or member data read to 0094 retrieve this data. It is these basic function calls that are then 0095 called in the subclasses of the Capability classes, with the 0096 top-level logic already standardized and done in the main 0097 MediaDeviceHandler class. 0098 0099 Note: To see the logic hereto referred, check the MediaDeviceHandler's 0100 calls to the Capability classes, and the order of the function calls. 0101 This helps to understand how best to map the functions of the 0102 Capability interface, to function calls or member-data access using the 0103 appropriate library. 0104 0105 2.3.2 Capabilities 0106 0107 ReadCapability - Maps the necessary functions to read the structs 0108 specific to the device, with the goal of parsing the entire device's 0109 metadata. Can also read the device's capacity, used and total. 0110 0111 WriteCapability - Receives generic commands related to writing to 0112 the device: find where to copy a new track onto the device, copy the 0113 track, delete the track. Subclass this Capability also to provide a full 0114 mapping onto the functions required to set the metadata on a newly 0115 created track struct, and the higher logic of in what order to do this 0116 is handled by the main Handler class. 0117 0118 ArtworkCapability - Optional. If the device supports artwork, this 0119 provides the interface for reading/writing that artwork. 0120 0121 PlaylistCapability - Optional. If the device supports playlists, this 0122 provides the interface for reading/writing playlists, parsing logic is 0123 based again on a linked-list struct that is traversed in a standard 0124 fashion. The subclass of this just maps to the appropriate functions 0125 to walk the linked list. 0126 0127 0128 3. Appendix/Notes 0129 0130 - At the time of writing, there isn't a full implementation of Solid on 0131 Windows or Mac, which limits support of devices mainly to Linux. Also, 0132 libraries used to interface at the low level (libgpod, libmtp) are 0133 Linux-specific.