Debian Codegraph @

HACKING/OUTDATED-MediaDeviceFramework

raw
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.