blob: b9ac1e6c015d5b56aef846ae67c89e68fc5ea785 [file] [log] [blame]
Linus Walleij0dd71e92006-05-04 18:47:07 +00001Building and Installing
2-----------------------
Linus Walleij6fd2f082006-03-28 07:19:22 +00003
Linus Walleij0dd71e92006-05-04 18:47:07 +00004See the "INSTALL" file.
5
6
Linus Walleij3f7529c2010-07-24 20:33:41 +00007Initiator and Responder
8-----------------------
9
10libmtp implements an MTP initiator, which means it initiate
11MTP sessions with devices. The devices responding are known
12as MTP responders. libmtp runs on something with a USB host
13controller interface, using libusb to access the host
14controller.
15
16If you're more interested in the MTP responders, gadgets like
Linus Walleij58a68772015-05-29 09:28:12 +020017MP3 players, mobile phones etc, look into:
18- MeeGo:s Buteo Sync:
19 https://github.com/nemomobile/buteo-mtp
20 https://wiki.merproject.org/wiki/Buteo/MTP
21- Android has an MTP responder implementation:
22 https://android.googlesource.com/platform/frameworks/base/+/master/media/jni/
23- Ubuntu/Ricardo Salveti has mtp-server and libmtp-server going:
24 https://code.launchpad.net/~phablet-team/mtp/trunk
25 http://bazaar.launchpad.net/~phablet-team/mtp/trunk/files
Linus Walleij3f7529c2010-07-24 20:33:41 +000026
Linus Walleij0dd71e92006-05-04 18:47:07 +000027Heritage
28--------
29
30libmtp is based on several ancestors:
31
32* libptp2 by Mariusz Woloszyn was the starting point used
33 by Richard A. Low for the initial starter port. You can
34 find it at http://libptp.sourceforge.net/
35
36* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
37 used at a later stage since it was (is) more actively
38 maintained. libmtp tracks the PTP implementation in
39 libgphoto2 and considers it an upstream project. We will
40 try to submit anything generally useful back to libgphoto2
41 and not make double efforts. In practice this means we
42 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
43 source code. If you need to change things in these files,
44 make sure it is so general that libgphoto2 will want to
45 merge it to their codebase too. You find libgphoto2 as part
46 of gPhoto: http://gphoto.sourceforge.net/
47
48* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000049 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000050 and made an generic C API he re-used the philosophy and
51 much code from libnjb. Many of the sample programs are for
52 example taken quite literally from libnjb. You find it here:
53 http://libnjb.sourceforge.net/
54
55
Linus Walleijea7d45b2009-02-23 22:26:09 +000056Contacting and Contributing
57---------------------------
58
59See the project page at http://libmtp.sourceforge.net/
60We always need your help. There is a mailinglist and a
61bug report system there.
62
63People who want to discuss MTP devices in fora seem to
64hang out on the forums at AnythingbutiPod:
65http://www.anythingbutipod.com/forum/
66
67
Linus Walleij0dd71e92006-05-04 18:47:07 +000068Compiling programs for libmtp
69-----------------------------
70
71libmtp has support for the pkg-config script by adding a libmtp.pc
72entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
73"just" write:
74
75gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
76
77This also simplifies compilation using autoconf and pkg-config: just
78write e.g.
79
80PKG_CHECK_MODULES(MTP, libmtp)
81AC_SUBST(MTP_CFLAGS)
82AC_SUBST(MTP_LIBS)
83
84To have libmtp LIBS and CFLAGS defined. Needless to say, this will
85only work if you have pkgconfig installed on your system, but most
86people have nowadays.
87
88If your library is installed in e.g. /usr/local you may have to tell
89this to pkgconfig by setting the PKG_CONFIG_PATH thus:
90
91export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
92
93
94Documentation
95-------------
96
97Read the API documentation that can be generated with doxygen.
98It will be output in doc/html if you have Doxygen properly
99installed. (It will not be created unless you have Doxygen!)
100
101For information about the Media Transfer Protocol, see:
102http://en.wikipedia.org/wiki/Media_Transfer_Protocol
103
Linus Walleij7a83e552008-07-29 21:30:43 +0000104The official 1.0 specification for MTP was released by the
105USB Implementers Forum in may, 2008. Prior to this, only a
106proprietary Microsoft version was available, and quite a few
107devices out there still use some aspects of the Microsoft
108version, which deviates from the specified standard. You can
109find the official specification here:
110http://www.usb.org/developers/devclass_docs/MTP_1.0.zip
Linus Walleij0dd71e92006-05-04 18:47:07 +0000111
Linus Walleij1b91ca62008-10-17 07:07:56 +0000112
113The Examples
114------------
115
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000116In the subdirectory "examples" you find a number of
Linus Walleij1b91ca62008-10-17 07:07:56 +0000117command-line tools, illustrating the use of libmtp in very
118simple terms.
119
120Please do not complain about the usability or documentation
121of these examples, they look like they do for two reasons:
122
1231. They are examples, not tools. If they were intended for
124 day-to-day usage by commandline freaks, I would have
125 called them "tools" not "examples".
126
1272. The MTP usage paradigm is that a daemon should hook
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000128 the device upon connection, and that it should be
Linus Walleij1b91ca62008-10-17 07:07:56 +0000129 released by unplugging. GUI tools utilizing HAL (hald)
130 and D-Bus do this much better than any commandline
131 program ever can. (See below on bugs.) Specificationwise
132 this is a bug, however it is present in many, many
133 devices.
134
135That said, if you want to pick up and maintain the examples,
136please volunteer.
137
138
Linus Walleijc36e2a62011-12-29 21:31:49 +0100139FAQ: Common Problems
140--------------------
141
142Some MTP devices have strange pecularities. We try to work around
143these whenever we can, sometimes we cannot work around it or we
144cannot test your solution.
145
Linus Walleij925acbe2012-11-13 21:37:40 +0100146* Android locked screen: some devices just report zero files
147 and no storages when the device screen is locked, it looks like
148 so:
149
150 mtp-detect
151 Device 0 (VID=04e8 and PID=6860) is a Samsung Galaxy models (MTP).
152 Attempting to connect device(s)
153 Error 1: Get Storage information failed.
154 Device: SHV-E210K
155 LIBMTP_Get_Storage(): No data available
156 OK.
157
158 This is probably so as not to allow the MTP access to be used
159 as a "backdoor" into the device. Unlock the device before listing
160 files, set the autolock to some large value or disabled if it
161 disturbs you, you are causing this to yourself, or should we say
162 that your vendor is prioritizing security and privacy over
163 ease-of-use. (You may talk to your vendor about this.)
164
Linus Walleijc36e2a62011-12-29 21:31:49 +0100165* mtp-* tools doesn't work because someone else is already hogging
166 the device
167
168 This is a common problem, the most common case could be that
169 gphoto2 (which can also talk PTP/MTP) is taking over the device
170 as soon as it's plugged in. Some distributions are configured that
171 way. Counter it like this:
172
173 gvfs-mount -s gphoto2
174
175 Then re-attach the device.
176
Linus Walleij5fff17e2012-07-18 23:49:05 +0200177 Sometimes the "gvfs-gphoto2-volume-monitor" is running on the
178 system and hogging the device, try something like:
179
Andrés G. Aragonesese92421a2015-03-31 15:42:49 +0200180 pkill gvfs-gphoto2-volume-monitor
Linus Walleij5fff17e2012-07-18 23:49:05 +0200181
Linus Walleijfb807262012-08-18 22:31:45 +0200182 Then plug in the device and issue "mtp-detect" to figure out if
183 this may be the case.
Linus Walleij5fff17e2012-07-18 23:49:05 +0200184
Linus Walleijc36e2a62011-12-29 21:31:49 +0100185* Generic MTP/PTP disconnect misbehaviour: we have noticed that
186 Windows Media Player apparently never close the session to an MTP
187 device. There is a daemon in Windows that "hooks" the device
188 by opening a PTP session to any MTP device, whenever it is
189 plugged in. This daemon proxies any subsequent transactions
190 to/from the device and will never close the session, thus
191 Windows simply does not close sessions at all.
192
Linus Walleije962add2012-01-13 20:22:22 +0100193 For example this means that a device may work the first time
194 you run some command-line example like "mtp-detect" while
195 subsequent runs fail.
196
Linus Walleijc36e2a62011-12-29 21:31:49 +0100197 Typical sign of this illness: broken pipes on closing sessions,
198 on the main transfer pipes(s) or the interrupt pipe:
199
200 Closing session
201 usb_clear_halt() on INTERRUPT endpoint: Broken pipe
202 OK.
203
204 This means that device manufacturers doesn't notice any problems
205 with devices that do not correctly handle closing PTP/MTP
206 sessions, since Windows never do it. The proper way of closing
207 a session in Windows is to unplug the device, simply put.
208
209 Since libmtp actually tries to close sessions, some devices
210 may fail since the close session functionality has never been
211 properly tested, and "it works with Windows" is sort of the
212 testing criteria at some companies.
213
Linus Walleije962add2012-01-13 20:22:22 +0100214 You can get Windows-like behaviour on Linux by running a udev-aware
Linus Walleijc36e2a62011-12-29 21:31:49 +0100215 libmtp GUI client like Rhythmbox or Gnomad2, which will "hook"
216 the device when you plug it in, and "release" it if you unplug
Linus Walleije962add2012-01-13 20:22:22 +0100217 it, and you start/end you transfer sessions by plugging/unplugging
218 the USB cable.
219
220 The "Unix way" of running small programs that open the device,
221 do something, then close the device, isn't really working with
222 such devices and you cannot expect to have command line tools
223 like the mtp examples work with them. You could implement new
224 example programs that just call to a mediating daemon like the
225 Windows MTP stack does. (And change all programs using libmtp
226 directly today.)
Linus Walleijc36e2a62011-12-29 21:31:49 +0100227
228 If this bug in your device annoys you, contact your device
229 manufacturer and ask them to test their product with some libmtp
230 program.
231
Linus Walleijf776f7b2012-06-06 10:14:05 +0200232* Samsung Android 2.3.x devices: these have a special MTP stack
233 with some specific bugs that we have maybe nailed down now.
234 It suffers from an "immediate connect" syndrome, i.e. you have
235 to connect to the device within 7 seconds of plugging in, or it
236 will go numb. This also goes for command-line activity with
237 the example programs, so this device is better used with a
238 GUI tool like Rhythmbox, gnomad2...
239
Linus Walleijc36e2a62011-12-29 21:31:49 +0100240* Generic USB misbehaviour: some devices behave badly under MTP
241 and USB mass storage alike, even down to the lowest layers
242 of USB. You can always discuss such issues at the linux-usb
243 mailing list if you're using Linux:
244 http://www.linux-usb.org/mailing.html
245
246 If you have a problem specific to USB mass storage mode, there
247 is a list of strange behaving devices in the Linux kernel:
248 http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h
249 You can discuss this too on the mentioned list, for understanding
250 the quirks, see:
251 http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt
252
253* Generic certificate misbehaviour. All devices are actually
254 required to support a device certificate to be able to
255 encrypt Windows Media (WMA/WMV) files. However there are
256 obviously a lot of devices out there which doesn't support
257 this at all but instead crash. Typical printout:
258
259 Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed
260 to get unicode property.
261
262 This should only affect "mtp-detect", there is no other
263 application currently retrieveing the certificate (not that we
264 know anyway).
265
266* Kernel bug on Linux. Linux 2.6.16 is generally speaking required
267 to use any MTP device under USB 2.0. This is because the EHCI
268 driver previously did not support zero-length writes to endpoints.
269 It should work in most cases however, or if you connect it
270 to an UHCI/OHCI port instead (yielding lower speed). But
271 please just use a recent kernel.
272
273* Zen models AVI file seeking problem: the Zens cannot parse the
274 files for the runlength metadata. Do not transfer file with e.g.
275 mtp-sendfile, use mtp-sendtr and set the length of the track to
276 the apropriate number of seconds and it will work. In graphical
277 clients, use a "track transfer" function to send these AVI files,
278 the Zens need the metadata associated with tracks to play back
279 movies properly. Movies are considered "tracks" in the MTP world.
280
281* Some devices that disregard the metadata sent with the MTP
282 commands will parse the files for e.g. ID3 metadata. Some still
283 of these devices expect only ID3v2.3 metadata and will fail with
284 a modern ID3v2,4 tag writer, like many of those found in Linux
285 applications. Windows Media Player use ID3v2.3 only, so many
286 manufacturers only test this version.
287
288* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
289 that makes it drop the last two characters off a playlist name.
290 It is fixed in later firmware.
291
292* For Creative Technology devices, there are hard limits on how
293 many files can be put onto the device. For a 30 GiB device (like
294 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
295 is 15000 files. For further Creative pecularities, see the
296 FAQ sections at www.nomadness.net.
297
298* Sandisk sansa c150 and probably several other Sandisk devices
299 (and possibly devices from other manufacturers) have a dual
300 mode with MTP and USB mass storage. The device will initially
301 claim to be mass storage so udev will capture is and make the
302 use of MTP mode impossible. One way of avoiding it could be to
303 be to blacklist the "usb-storage" module in
304 /etc/modprobe.c/blacklist with a row like this:
305 "blacklist usb-storage". Some have even removed the
306 "usb-storage.ko" (kernel module file) to avoid loading.
307
308* Sandisk Sansa Fuze has three modes: auto, MTP or mass storage
309 (MSC). Please set it to MTP to avoid problems with libmtp.
310
311* The iriver devices (possibly all of them) cannot handle the
312 enhanced GetObjectPropList MTP command (0x9805) properly. So
313 they have been banned from using it.
314
315* iriver devices have problems with older versions of libmtp and
316 with new devices libmtp does not know of as of yet, since it
317 has an oldstyle USB device controller that cannot handle zero
318 writes. (Register your device with us!) All their devices are
319 likely to need a special device flag in the src/libusb-glue.c
320 database.
321
322* The Samsung Yepp T9 has several strange characteristics, some
323 that we've managed to work around. (For example it will return
324 multiple PTP packages in a single transaction.)
325
326* The early firmware for Philips HDD players is known to be
327 problematic. Please upgrade to as new firmware as you can get.
328 (Yes this requires some kind of Windows Installation I think.)
329
330* Philips HDD 1630/16 or 1630/17 etc may lock themselves up,
331 turning inresponsive due to internal corruption. This typically
332 gives an error in opening the PTP session. Apparently you can
333 do a "repair" with the firmware utility (Windows only) which
334 will often fix this problem and make the device responsive
335 again.
336
337* Some devices that implement GetObjectPropList (0x9805) will
338 not return the entire object list if you request a list for object
339 0xffffffffu. (But they should.) So they may need the special
340 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
341
342* Some (smaller) subset of devices cannot even get all the
343 properties for a single object in one go, these need the
344 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
345 iriver devices seem to have this bug.
346
347* The Toshiba Gigabeat S (and probably its sibling the
348 Microsoft Zune and other Toshiba devices) will only display
349 album information tags for a song in case there is also
350 an abstract album (created with the album interface) with
351 the exact same name.
352
353* The Zen Vision:M has an older firmware which is very corrupt,
354 it is incompatible with the Linux USB stack altogether. The
355 kernel dmesg will look something like this, and you have to
356 upgrade the firmware using Windows:
357 usb 4-5: new high speed USB device using ehci_hcd and address 5
358 usb 4-5: configuration #1 chosen from 1 choice
359 usb 4-5: can't set config #1, error -110
360
361* The Sirus Stiletto does not seem to allow you to copy any files
362 off the device. This may be someone's idea of copy protection.
363
364* The Samsung P2 assigns parent folder ID 0 to all unknown file
365 types.(i.e. moves them to the root folder)
366
367* The Sandisk Sansa Clip+ needs a firmware upgrade in earlier
368 versions in order to work properly.
369
370
Linus Walleija1b66f22007-05-10 20:02:16 +0000371New Devices
372-----------
373
Linus Walleijfcf88912006-06-05 13:23:33 +0000374If you happen upon a device which libmtp claims it cannot
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000375autodetect, please submit the vendor ID and device ID
Linus Walleij9ee29402007-10-31 20:24:48 +0000376(these can be obtained from the "lsusb" and "lsusb -n"
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000377commands run as root) as a bug, patch or feature request
378on the Sourceforge bug tracker at our homepage. If it
379gives a sensible output from "mtp-detect" then please attach
380the result as well as it teach us some stuff about your
381device. If you've done some additional hacking, join our
Linus Walleij9ee29402007-10-31 20:24:48 +0000382mailinglist and post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +0000383
Linus Walleija1b66f22007-05-10 20:02:16 +0000384If you want to be able to hack some more and you're not
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000385afraid of C hacking, add an entry for your device's
386vendor/product ID and a descriptive string to the database
Linus Walleij6dc01682007-11-15 21:23:46 +0000387in the file src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000388
389If you want to poke around to see if your device has some
390special pecularities, you can test some special device
Linus Walleij6dc01682007-11-15 21:23:46 +0000391flags (defined in src/device-flags.h) by inserting them
392together with your device entry in src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000393Flags can be tested in isolation or catenated with "|"
394(binary OR). If relatives to your device use a certain
395flag, chances are high that a new device will need it
396too, typically from the same manufacturer.
397
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000398The most common flag that needs to be set is the
Linus Walleija1b66f22007-05-10 20:02:16 +0000399DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
400drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000401MTP access impossible. This is however not expected to
402really work: this is a problem being tracked as of
403now (2007-08-04). See the "last resort" solutions below
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000404if you really need to get your dual-mode device to work
Linus Walleij94f23d52007-08-04 19:37:28 +0000405with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000406
Linus Walleijcc2cf972007-11-22 20:23:43 +0000407Another flag which is easy to identify is the
408DEVICE_FLAG_NO_ZERO_READS, which remedies connection
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000409timeouts when getting files, and some timeouts on e.g.
Linus Walleijcc2cf972007-11-22 20:23:43 +0000410successive "mtp-connect" calls.
411
Linus Walleija1b66f22007-05-10 20:02:16 +0000412If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000413works under Windows, so we enjoy reading USB packet sniffs
414that reveal the low-level traffic carried out between
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000415Windows Media Player and your device. This can be done
Linus Walleij61c25682007-09-04 14:46:21 +0000416using e.g.:
417
418* USBsnoop:
419 http://benoit.papillault.free.fr/usbsnoop/
420
421* The trial version of HHD Softwares software-only
422 USB monitor. You need to get a copy of version 2.37 since
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000423 the newer trial versions won't let you carry out the
Linus Walleij61c25682007-09-04 14:46:21 +0000424 needed packet sniffs. (As of 2007-03-10 a copy can be found
425 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
426
Linus Walleijda558be2007-03-10 21:42:25 +0000427There are other USB monitors as well, some more expensive
428alternatives use hardware and even measure electronic
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000429characteristics of the traffic (which is far too much
Linus Walleijda558be2007-03-10 21:42:25 +0000430detail for us).
431
Linus Walleij91fb0282007-09-03 21:16:08 +0000432Device sniffs are an easy read since the PTP/MTP protocol
433is nicely structured. All commands will have a structure such
434as this in the log, we examplify with a object list request:
435
436PTP REQEUST:
437000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
438Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
439Send 0x20 bytes to the device:
440 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
441 Length TYPE CMD Trans# Param1
442
443 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ăœ..........
444 Param2 Param3 Param4 Param5
445
446[OPTIONAL] DATA PHASE:
447000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
448Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
449Get 0x1a bytes from the device:
450 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
451 Length TYPE CMD Trans# DATA
452
453 27 03 00 10 02 DC 04 00 00 30 '....Ăœ...0
454
455RESPONSE:
456000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
457Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
458Get 0xc bytes from the device:
459 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
460 Length TYPE CODE Trans#
461
462* One send (OUT to the device), two reads (IN from the device).
463
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000464* All three byte chunks commands are
465 sent/recieved/recieeved by the function ptp_transaction()
Linus Walleij91fb0282007-09-03 21:16:08 +0000466 in the file ptp.c.
467
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000468* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
469 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
Linus Walleij91fb0282007-09-03 21:16:08 +0000470 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
471 are ALWAYS called. The TYPE field correspond to this, so the
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000472 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
Linus Walleij91fb0282007-09-03 21:16:08 +0000473 and "RESPONSE" (0x0003).
474
475* Notice that the byte order is little endian, so you need to read
476 each field from right to left.
477
478* This COMMAND has:
479 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
480 Transaction# 0x00000023.
481 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
482 0x00000000, in this case it means "get props for object 0x10000327",
483 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
484 parameters that are always zero (no idea what they mean or their
485 use).
486
487* The DATA has:
488 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
489 Transaction# 0x00000023.
490 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
491 Which means in this case, (and this is the tricky part) "here
492 you have 1 property", "for object 0x10000327", "it is property
493 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
494 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
495 is perfectly valid to have undefined object formats, since it
496 is a legal value defining this).
497
498* This RESPONSE has:
499 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
500 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000501 Transaction# 0x00000023.
Linus Walleijfcf88912006-06-05 13:23:33 +0000502
Linus Walleijd05fce62007-09-29 20:17:23 +0000503If you want to compare the Windows behaviour with a similar
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000504operation using libmtp you can go into the src/libusb-glue.c
Linus Walleij6dc01682007-11-15 21:23:46 +0000505file and uncomment the row that reads:
Linus Walleijd05fce62007-09-29 20:17:23 +0000506
507//#define ENABLE_USB_BULK_DEBUG
508
509(I.e. remove the two //.)
510
511This will make libmtp print out a hex dump of every bulk USB
512transaction. The bulk transactions contain all the PTP/MTP layer
513data, which is usually where the problems appear.
514
Linus Walleij6fd2f082006-03-28 07:19:22 +0000515
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200516Notes to assist with debugging new devices:
517-------------------------------------------
518
Linus Walleijc36e2a62011-12-29 21:31:49 +0100519In debugging new hardware, we highly recommend that you only
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200520use the example mtp-* applications that come with libmtp, as other
521applications may have their own bugs that may interfere with your
522new device working correctly. Using another application instead of
523those that come with libmtp just adds another point of failure.
524
525For debugging, there are 3 main options:
526
Linus Walleijc36e2a62011-12-29 21:31:49 +01005271. Use the env variable: LIBMTP_DEBUG to increase the
528verboseness of the debugging output for any application using
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200529libmtp. Relevant codes are:
530* 0x00 [0000 0000] : no debug (default)
531* 0x01 [0000 0001] : PTP debug
532* 0x02 [0000 0010] : Playlist debug
533* 0x04 [0000 0100] : USB debug
534* 0x08 [0000 1000] : USB data debug
535// Codes are hex and binary respectively. Simple add them togther
536// to get your desired level of output.
537
538(Assuming bash)
Linus Walleijc36e2a62011-12-29 21:31:49 +0100539eg:
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200540$ export LIBMTP_DEBUG=12
541$ mtp-detect
542 // To get USB debug and USB data debug information.
543
544$ export LIBMTP_DEBUG=2
545$ mtp-detect
546 // To get Playlist debug information.
Linus Walleijc36e2a62011-12-29 21:31:49 +0100547
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200548Also note, an application may also use the LIBMTP_debug() API
549function to achieve the same options as listed above.
550
Linus Walleijc36e2a62011-12-29 21:31:49 +01005512. Use "strace" on the various mtp-* commands to see where/what
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200552is falling over or getting stuck at.
553* On Solaris and FreeBSD, use "truss" or "dtrace" instead on "strace".
554* On Mac OS X, use "ktrace" or "dtrace" instead of "strace".
555* On OpenBSD and NetBSD, use "ktrace" instead of "strace".
556
557This will at least help pinpoint where the application is failing, or
Linus Walleijc36e2a62011-12-29 21:31:49 +0100558a device is reporting incorrect information. (This is extremely helpful
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200559with devices that have odd disconnection requirements).
560
Linus Walleijc36e2a62011-12-29 21:31:49 +0100561The use of these tools may also pinpoint issues with libusb as
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200562implemented by each OS vendor or issues with the MTP implementation
563on the new device as well, so please be prepared for either case.
564
5653. Use "gdb" or similar debugger to step through the code as it is
566run. This is time consuming, and not needed just to pinpoint where
Linus Walleijc36e2a62011-12-29 21:31:49 +0100567the fault is.
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200568
Linus Walleijc36e2a62011-12-29 21:31:49 +0100569The use of gdb or another debugger may also miss or actually cause
570command and data timing issues with some devices, leading to false
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200571information. So please consider this a last resort option.
572
573Also please read the "It's Not Our Bug!" section below, as it does
574contain some useful information that may assist with your device.
575
576
Linus Walleij8d799eb2009-07-23 22:58:06 +0000577Dual-mode devices does not work - last resort:
578----------------------------------------------
Linus Walleijbd7624c2007-05-28 10:48:54 +0000579
580Some devices that are dual-mode are simply impossible to get
581to work under Linux because the usb-storage(.ko) kernel
582module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000583when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
584it DOES release it but the device will immediately be probed
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000585at the USB mass storage interface AGAIN because it
Linus Walleij94f23d52007-08-04 19:37:28 +0000586enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000587
Linus Walleij8d799eb2009-07-23 22:58:06 +0000588Here is what some people do:
589
590 1. Plug in the device.
591 2. USB-mass storage folder will open automatically.
592 3. Unmount the device.
593 4. Run mtp-detect. It will most likely fail the first time.
594 5. Run mtp-detect again, it might work this time, or fail. Keep running
595 till it works. 99% it works by the third try.
596 6. Once mtp-detect gives you an "Ok", open either Rhythmbox or Gnomad2,
597 everything should work.
598
Linus Walleij1b9f1642013-07-07 22:57:23 +0200599Linux: Try this, if you have a recent Linux kernel,
600add the file (as root):
601
602/etc/modprobe.d/no-usb-storage.conf
603
604With the contents:
605
606options usb-storage quirks=1234:4321:i
607
608This will tell usb-storage to ignore this device when it's inserted
609so it is not hogged by the mass storage interfaces. Remove and re-insert
610the device and see if it works. Usually this does the trick.
611
612For older systems, or as a bigger hammer, run (as root) something
613like:
Linus Walleij584eb8d2007-09-05 19:51:27 +0000614
615> rmmod usb_storage ; mtp-detect
616
617You can run most any command or a client like gnomad2 or
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000618Amarok immediately after the rmmod command. This works
Linus Walleij1b9f1642013-07-07 22:57:23 +0200619sometimes. Another even more brutal approach is this:
Linus Walleijbd7624c2007-05-28 10:48:54 +0000620
Linus Walleij94f23d52007-08-04 19:37:28 +0000621* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000622* Add the line "blacklist usb-storage"
Linus Walleijbd7624c2007-05-28 10:48:54 +0000623* Reboot.
624
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000625Now none of you USB disks, flash memory sticks etc will be
Linus Walleijbd7624c2007-05-28 10:48:54 +0000626working (you just disabled them all). However you *can* try
627your device, and it might have started working because there
628is no longer a USB mass storage driver that tries to hook onto
629the mass storage interface of your device.
630
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000631If not even blacklisting works (check with
Linus Walleij94f23d52007-08-04 19:37:28 +0000632"lsmod | grep usb-storage"), there is some problem with
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000633something else and you may need to remove or rename the file
Linus Walleij94f23d52007-08-04 19:37:28 +0000634/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
635manually.
636
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000637If you find the PerfectSolution(TM) to this dilemma, so you
Linus Walleijbd7624c2007-05-28 10:48:54 +0000638can properly switch for individual devices whether to use it
639as USB mass storage or not, please tell us how you did it. We
640know we cannot use udev, because udev is called after-the-fact:
641the device is already configured for USB mass storage when
642udev is called.
643
Linus Walleije20abaf2007-12-10 11:20:34 +0000644On Mac OS there is another ugly hack:
645
6461. Open up a terminal window
6472. Type:
648sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
649/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
650
651and when prompted enter your password.
652
6533. Restart.
654
655To reverse this change, just reverse the filenames:
656
657sudo mv /System/Library/Extensions/
658IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
659IOUSBMassStorageClass.kext
660
661and restart.
662
Linus Walleijbd7624c2007-05-28 10:48:54 +0000663
Linus Walleij15def332006-09-19 14:27:02 +0000664Calendar and contact support:
665-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000666
Linus Walleij3c16fe42006-04-30 07:53:41 +0000667The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000668and VCard (.vcf) files from programs like for example
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000669Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000670
Linus Walleij3c16fe42006-04-30 07:53:41 +0000671- The file must be in DOS (CR/LF) format, use the unix2dos
672 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000673
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000674- Repeat events in calendar files do not seem to be supported,
Linus Walleij15def332006-09-19 14:27:02 +0000675 entries will only appear once.
676
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000677- Calendar (.ics) files should be stored in the folder "My Organizer"
Linus Walleij15def332006-09-19 14:27:02 +0000678 when sent to the device (this directory should be autodetected
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000679 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000680 -f "My Organizer" to sendfile for this) Apparently this file can
681 also contain tasklists.
682
683- Contact (.vcf) files should be stored in the folder "My Contacts"
684 when sent to the device. (-f "My Contacts")
685
686- Some devices are picky about the name of the calendar and
687 contact files. For example the Zen Microphoto wants:
688
Linus Walleijb1318d12006-09-25 14:59:26 +0000689 Calendar: My Organizer/6651416.ics
690 Contacts: My Organizer/6651416.vcf
691
692
693Syncing in with Evolution and Creative Devices
694----------------------------------------------
695
696Evolution can easily export .ics an .vcf files, but you currently
697need some command-line hacking to get you stuff copied over in
698one direction host -> device. The examples/ directory contains a script
699created for the Creative Zen Microphoto by Nicolas Tetreault.
700
Linus Walleij6e8cef42006-12-03 20:45:04 +0000701
Linus Walleijd132d8e2007-04-03 23:24:54 +0000702Lost symbols
703------------
704
705Shared libraries can be troublesome to users not experienced with
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000706them. The following is a condensed version of a generic question
Linus Walleijd132d8e2007-04-03 23:24:54 +0000707that has appeared on the libmtp mailing list from time to time.
708
709> PTP: Opening session
710> Queried Creative Zen Vision:M
711> gnomad2: relocation error: gnomad2: undefined symbol:
712> LIBMTP_Get_Storageinfo
713> (...)
714> Are these type of errors related to libmtp or something else?
715
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000716The problem is of a generic nature, and related to dynamic library
Linus Walleijd132d8e2007-04-03 23:24:54 +0000717loading. It is colloquially known as "dependency hell".
718(http://en.wikipedia.org/wiki/Dependency_hell)
719
720The gnomad2 application calls upon the dynamic linker in Linux to
721resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
722(ELF symbol, or link point or whatever you want to call them, a
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000723symbol is a label on a memory address that the linker shall
Linus Walleijd132d8e2007-04-03 23:24:54 +0000724resolve from label to actual address.)
725For generic information on this subject see the INSTALL file and
726this Wikipedia page:
727
728http://en.wikipedia.org/wiki/Library_(computing)
729
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000730When Linux /lib/ld-linux.so.X is called to link the symbols compiled
731into gnomad2 (or any other executable using libmtp), it examines the
732ELF file for the libmtp.so.X file it finds first and cannot resolve
Linus Walleijd132d8e2007-04-03 23:24:54 +0000733the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000734problem witj) from it, since it's probably not there. There are many
Linus Walleijd132d8e2007-04-03 23:24:54 +0000735possible causes of this symbol breakage:
736
7371) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
738 whatever) that do not match up. Typical cause: your gnomad2 package was
739 built against a newer version of libmtp than what's installed on your
740 machine. Another typical cause: you installed a package you found on
741 the web, somewhere, the dependency resolution system did not protest
742 properly (as it should) or you forced it to install anyway, ignoring
743 some warnings.
744
7452) You compiled libmtp and/or gnomad2 from source, installing both or
746 either in /usr/local/lib and /usr/local/bin. This means at compile-time
747 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
748 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
749 order to resolve the symbols. This loader will look into the file
750 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
751 paths to libraries to be used for resolving the symbols. If you have
752 some older version of libmtp in e.g. /usr/lib (typically installed by a
753 package manager) it will take precedence over the new version you just
754 installed in /usr/local/lib and the newly compiled library in
755 /usr/local/lib will *not* be used, resulting in this error message.
756
7573) You really did install the very latest versions (as of writing libmtp
758 0.1.5 and gnomad2 2.8.11) from source and there really is no
759 pre-installed package of either on your machine. In that case I'm
760 totally lost, I have no idea what's causing this.
761
762Typical remedies:
763
7641) If you don't want to mess around with your system and risk these
765 situations, only use pre-packaged software that came with the
766 distribution or its official support channels. If it still breaks,
767 blame your distribution, they're not packaging correctly. Relying on
768 properly packaged software and not installing things yourself *is* the
769 Linux solution to the "dependency hell" problem.
770
7712) Read about dynamically linked library handling until the stuff I wrote
772 about in the previous list sounds like music to your ears, inspect
773 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
774 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
775 YaST or whatever your distribution uses, compile libmtp and gnomad2
776 (or whatever) from source only and you will be enlighted.
777
778I don't know if this helps you, it's the best answer we can give.
Linus Walleij387e37a2008-10-29 17:22:22 +0000779
780
781API is obscure - I want plain files!
782------------------------------------
783
784PTP/MTP devices does not actually contain "files", they contain
785objects. These objects have file names, but that is actually
786just a name tag on the object.
787
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000788Folders/directories aren't really such entities: they are just
Linus Walleij387e37a2008-10-29 17:22:22 +0000789objects too, albeit objects that can act as parent to other
Linus Walleij8aba06d2008-12-28 08:26:57 +0000790objects. They are called "associations" and are created in atomic
Linus Walleij387e37a2008-10-29 17:22:22 +0000791fashion and even though there is an MTP command to get all the
Linus Walleij514e2eb2012-09-02 16:55:45 +0200792associations of a certain object, this command is optional
Linus Walleij8aba06d2008-12-28 08:26:57 +0000793so it is perfectly possible (and most common, actually) to create
794devices where the "folders" (which are actually associations) have
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000795no idea whatsoever of what files they are associated as parents to
Linus Walleij387e37a2008-10-29 17:22:22 +0000796(i.e. which files they contain). This is very easy for device
Linus Walleij8aba06d2008-12-28 08:26:57 +0000797manufacturers to implement, all the association (i.e. finding out
798which files are in a certain folder) has to be done by the MTP
799Initiator / host computer.
Linus Walleij387e37a2008-10-29 17:22:22 +0000800
801Moving a file to a new folder is for example very simple in a
802"real" file system. In PTP/MTP devices it is often not even possible,
Linus Walleij514e2eb2012-09-02 16:55:45 +0200803some devices *may* be able to do that, if they support command
8040x1019 "Move Object", but actually the only reliable way of executing
805file movement is to upload the file to the host, download it with
806the new parent, then delete the old file. We have played with the
807idea of implementing this time consuming function as a fallback
808in case the device does not support command 0x1019, perhaps one day
809we will do that. (Some devices also support command 0x101a
810"Copy Object".)
Linus Walleij387e37a2008-10-29 17:22:22 +0000811
Linus Walleij8aba06d2008-12-28 08:26:57 +0000812Then the issue that in PTP/MTP it is legal for two files to have
813exactly the same path as long as their object IDs differ. A
814folder/association can contain two files with the exact same name.
815(And on the Creative devices this even works, too, though most devices
816implicitly fail at this.) Perhaps one could add some custom hook for
817handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something
818similar, but it's really a bit kludgy.
819
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000820Playlists and albums aren't really files, thinking about
Linus Walleij387e37a2008-10-29 17:22:22 +0000821them as files like the hacks in libgphoto2 is really backwards. They are
822called associations and are more like a symbolic link that links in a
823star-shaped pattern to all the files that are part of the album/playlist.
824Some devices (Samsung) thought that was too complicated and have a
825different way of storing playlists in an UTF-16 encoded .spl-like file
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000826instead! This is why playlists/albums must have their own structs and
Linus Walleij387e37a2008-10-29 17:22:22 +0000827functions.
828
Linus Walleij8aba06d2008-12-28 08:26:57 +0000829Plain file access also assumes to be able to write files of an
830undetermined size, which is simply not possible in a transactional
831file system like PTP/MTP. (See further below.)
832
Linus Walleij387e37a2008-10-29 17:22:22 +0000833
834I Want Streaming!
835-----------------
836
837Streaming reads is easy. Just connect the output file descriptor from
838LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)
839wherever you want.
840
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000841People have connected this to TCP sockets for streaming web servers
842etc, works like a charm. Some devices will even survive if the callback
Linus Walleij387e37a2008-10-29 17:22:22 +0000843functions return non-zero and cancel the download. Some devices will
844lock up and even require a reset if you do that. Devices are poorly
845implemented so that's life. If you want to stream off a device, the
846best idea is always to stream the entire file and discard the stuff
847at the end you don't want. It will incur a delay if you e.g. want to
848skip between tracks, sadly.
849
850Then we get to the complicated things: streaming WRITES...
851
852There is a function:
853LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks)
854which will write a file to a device from a file descriptor, which may
855be a socket or whatever.
856
857HOWEVER: this requires a piece of metadata with the .filesize properly
858set first.
859
860This is not because we think it is funny to require that, the protocol
861requires it. The reason is that PTP/MTP is a transactional file system
862and it wants to be able to deny file transfer if the file won't fit on
863the device, so the transaction never even starts, it's impossible to
864start a transaction without giving file length.
865
866People really want streaming so I tried a lot of hacks to see if they
867would work, such as setting file size to 0xffffffffU or something other
868unnaturally big and then aborting the file transfer when the stream ends.
869It doesn't work: either the device crashes or the file simply disappears
870since the device rolls back all failed transactions.
871
872So this is an inherent limitation of the PTP/MTP protocol.
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000873
874
Linus Walleijae890212012-02-16 01:56:19 +0100875I want to remote control my device!
876-----------------------------------
877
878I have both good and bad news for you.
879
880The good news is that the MTP protocol has well-defined commands to play
881back content on a device. Operation 0xD411 (PTP_DPC_MTP_PlaybackObject)
882will start playing back a file on the device (whatever that may mean if
883this is not a music or video file), and operation 0xD403 can set the
884playback volume to save your ears. Then there are operations to
885determine how far into the current file you currently are, so as to
886support say progress bars.
887
888Since these commands have been around since the dawn of the MTP protocol
889and since it was developed in cooperation with Creative Technology, this
890is probably a requested feature from the Creative people who already had
891support for playback on their devices using the PDE protocol back then.
892
893Anyway, here are the bad news:
894[logs]$ grep d411 *
895mtp-detect-trekstor-vibez.txt: 0xd411: Playback Object
896
897Aha there is only one known device in the world which actually supports
898playback on the device. So either you go buy the Trekstor Vibez, or you
899can forget about this. You could always try asking your hardware vendor
900of choice to go implement this.
901
902Since none of the core developers of libmtp has the Trekstor device, this
903is not yet implemented in libmtp.
904
905
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000906I make MTP devices!
907-------------------
908
909If you are a device vendor there is a lot you can do for libmtp:
910
911* Please consider assigning one of your employees as a contact person
912 for libmtp, have them sign up to the libmtp development list and answer
913 questions and post new device ID:s as they are released to our
914 mailing list.
915
916* If you want to help even more, assign someone to look deeper into
917 error reports on your specific devices, understand why your firmware
918 may require some special device flags and what can be done about it.
919
920* Do you have spare devices you can give us? Send them to Richard (Mac
921 support) or Linus (Linux support). (So far nobody did that except for
922 Microsoft who sent us a Zune by proxy!)
923
924Vendors do need help from libmtp too, especially we want to help
925vendors improve their MTP stacks, because they all suffer from the
926same problem: the lack of a proper conformance test has made many devices
927incompliant with the MTP specification as it is published today: most
928devices are just compliant with the Windows MTP stack, and don't work
929out-of-the-box with libmtp. We need someone on the inside to help in
930bug reporting vendors MTP stacks internally so these issues are raised.
931A good way to go toward better MTP compliance is to test with an
932alternative implementation of the stack. In e.g. IETF standardization
933it is compulsory for an RFC to have atleast two independent implementations
934for it to reach the status as standard.
935
936Being compliant with libmtp is also more and more important for
937vendors: libmtp is being deployed in some embedded systems like
938set-top-boxes etc. It will be very irritating for customers if a device
939will not dock properly with some home entertainment equipment just because
940it is based on Linux and libmtp and not the Windows MTP stack.
Linus Walleij5f5c69f2011-06-26 14:34:13 +0200941
942Autodetect with gudev
943---------------------
944
945Previously you would use HAL to detect devices being plugged in. Nowadays
946we use udev directly, or though the GNOME libgudev library. LIBMTPs
947default udev rules export the proper properties to detect any MTP device
948automatically, here is a verbose example derived from gnomad2:
949
950#define G_UDEV_API_IS_SUBJECT_TO_CHANGE
951#include <gudev/gudev.h>
952const char * const gudev_subsystems[] = { "usb", NULL };
953GUdevClient *gudev_client;
954guint uevent_id;
955guint uevent_bus_hooked = 0;
956guint uevent_device_hooked = 0;
957
958
959static void uevent_cb(GUdevClient *client, const char *action, GUdevDevice *device, void *data)
960{
961 guint64 devicenum;
962 guint vendor;
963 guint model;
964 guint busnum;
965 guint devnum;
966 guint mtpdevice;
967
968 devicenum = (guint64) g_udev_device_get_device_number(device);
969 g_print("%s event for %s (%"G_GINT64_MODIFIER"x)", action,
970 g_udev_device_get_sysfs_path (device), devicenum);
971
972 /* get device info */
973 vendor = get_property_as_int(device, "ID_VENDOR_ID", 16);
974 model = get_property_as_int(device, "ID_MODEL_ID", 16);
975 busnum = get_property_as_int(device, "BUSNUM", 10);
976 devnum = get_property_as_int(device, "DEVNUM", 10);
977 mtpdevice = get_property_as_int(device, "ID_MTP_DEVICE", 10);
978
979 if (vendor == 0 || model == 0) {
980 g_print("couldn't get vendor or model ID for device at (%x:%x)\n",
981 busnum, devnum);
982 return;
983 } else {
984 g_print("vendor = %x, model = %x, bus = %x, device = %x\n",
985 vendor, model, busnum, devnum);
986 }
987
988 if (mtpdevice) {
989 g_print("device is MTP compliant\n");
990
991 if (g_str_equal(action, "add") &&
992 uevent_bus_hooked == 0 &&
993 uevent_device_hooked == 0) {
994 g_print(MTP device plugged in!\n");
995 uevent_bus_hooked = busnum;
996 uevent_device_hooked = devnum;
997 scan_jukebox(NULL);
998 } else if (g_str_equal (action, "remove") &&
999 uevent_bus_hooked == busnum &&
1000 uevent_device_hooked == devnum) {
1001 g_print("MTP device removed!\n");
1002 uevent_bus_hooked = 0;
1003 uevent_device_hooked = 0;
1004 }
1005 }
1006}
1007
1008
1009
1010(...)
1011 /*
1012 * Monitor udev device events - we're only really interested in events
1013 * for USB devices.
1014 */
1015 gudev_client = g_udev_client_new(gudev_subsystems);
1016 uevent_id = g_signal_connect_object(gudev_client,
1017 "uevent",
1018 G_CALLBACK(uevent_cb),
1019 NULL, 0);
Linus Walleij187ac2f2012-05-02 19:08:03 +02001020
1021SKETCH OF AN OVERVIEW
1022---------------------
1023
1024Draft agenda for a talk on MTP devices submitted for the Android
1025builders summit, might come to recycle this:
1026
1027- Protocol overview
Linus Walleijb35c1132012-09-03 07:45:30 +02001028 - Transactional filesystem - no corruption due to unplugged cables!
Linus Walleijfd9132c2013-03-05 10:43:49 +01001029 - The host and the device can access the files simultaneously, the
1030 device will always "own" the physical file system and proxy the
1031 host (MTP initiator).
Linus Walleij187ac2f2012-05-02 19:08:03 +02001032- libmtp interface
1033- relation to libgphoto2
Linus Walleijb35c1132012-09-03 07:45:30 +02001034- User expectations fall short:
1035 - Not really a mountable filesystem.
1036 - Streaming does not work. (Size needs to be known beforehand due to
1037 transactional nature.)
Linus Walleijfd9132c2013-03-05 10:43:49 +01001038 - GVFS MTP backend to the rescue.
Linus Walleij187ac2f2012-05-02 19:08:03 +02001039- Device sins
Linus Walleijd33763a2013-11-06 05:05:20 +01001040 - Using the same VID/PID for several modes, some of which are not MTP.
1041 HTC Zopo, HD2, Bird (0x0bb4/0x0c02). Thanks for that, now we cannot
1042 detect the protocol from just VID+PID but have to examine the interfaces.
Linus Walleij187ac2f2012-05-02 19:08:03 +02001043 - Android bugs
1044 - Samsungs special Android MTP stack
1045 - SonyEricsson Aricent stack for Xperia Androids pre 4.0, broken headers!
Linus Walleij6bc5d262012-09-02 17:45:42 +02001046 - Flat access model vs hierarchical, how Android uses MTP as an hierachical
1047 file system while it was previously a flat database.
Linus Walleijfd9132c2013-03-05 10:43:49 +01001048 - Old paradigm: scan the entire non-hierarchical storage for all content,
1049 build a cache to speed up the (USB 1.1!) link. Usually all files were
1050 stored in the root folder or a single folder named "/Music" or similar.
1051 - Android introduced deeply nested folder hierarchies, not seen before
1052 on MTP devices.
1053 - Microsoft not using the complete metadata dump feature of the MTP
1054 protocol (once introduced by creative) instead they walk directories
1055 separately.
1056 - So caching a big device will take long time and/or timeout.
1057 - Go-MTPFS (FUSE) and GVFS MTP - doing the partial directory walk rather
1058 than caching all files.
Linus Walleij40397102013-04-29 11:38:03 +02001059 - Especially Android devices nowadays assume that
1060 you want to index a folder at the time, whereas older MTP devices (such
1061 as those from Creative) would assume that you wanted to index the entire
1062 device as it was plugged in, and device firmware is now ever more tailored
1063 toward per-folder filetree walking. This makes it harder for the library
1064 to provide the right abstractions: do we provide an API for indexing the
1065 whole device which is unacceptably slow on new devices, or do we provide
1066 an API for indexing a directory at the time which will somehow work on
1067 older devices too? Shall we deprecate the older API?
Linus Walleij187ac2f2012-05-02 19:08:03 +02001068- Detecting from vendor extension, can fix in newer extensions!
1069- Autoprobing on Linux
1070 - Color devices do not like autoprobing
Linus Walleij7237d6a2012-08-18 22:50:21 +02001071 - Devices need different PIDs for every alternative interface due to
1072 the Windows USB stack.
Linus Walleijb35c1132012-09-03 07:45:30 +02001073 - Multimode USB - one PID for each mode due to Windows limitations not
1074 applicable to Linux, SONY devices have ~5 different PIDs for a single
1075 device.
Linus Walleijfd9132c2013-03-05 10:43:49 +01001076 - Mode switch devices? Maybe we do this wrong.
1077- MTPZ, came and went. Apparently deprecated by Microsoft with Windows
1078 Phone 8.
Linus Walleijb35c1132012-09-03 07:45:30 +02001079- Ideas??
1080