blob: 3c026ff615bb7e6d330d77be453d28205db60ea4 [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
17MP3 players, mobile phones etc, look into MeeGo:s Buteo Sync:
18http://wiki.meego.com/Buteo - these guys are creating a fully
19open source MTP responder.
20
21
Linus Walleij0dd71e92006-05-04 18:47:07 +000022Heritage
23--------
24
25libmtp is based on several ancestors:
26
27* libptp2 by Mariusz Woloszyn was the starting point used
28 by Richard A. Low for the initial starter port. You can
29 find it at http://libptp.sourceforge.net/
30
31* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
32 used at a later stage since it was (is) more actively
33 maintained. libmtp tracks the PTP implementation in
34 libgphoto2 and considers it an upstream project. We will
35 try to submit anything generally useful back to libgphoto2
36 and not make double efforts. In practice this means we
37 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
38 source code. If you need to change things in these files,
39 make sure it is so general that libgphoto2 will want to
40 merge it to their codebase too. You find libgphoto2 as part
41 of gPhoto: http://gphoto.sourceforge.net/
42
43* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000044 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000045 and made an generic C API he re-used the philosophy and
46 much code from libnjb. Many of the sample programs are for
47 example taken quite literally from libnjb. You find it here:
48 http://libnjb.sourceforge.net/
49
50
Linus Walleijea7d45b2009-02-23 22:26:09 +000051Contacting and Contributing
52---------------------------
53
54See the project page at http://libmtp.sourceforge.net/
55We always need your help. There is a mailinglist and a
56bug report system there.
57
58People who want to discuss MTP devices in fora seem to
59hang out on the forums at AnythingbutiPod:
60http://www.anythingbutipod.com/forum/
61
62
Linus Walleij0dd71e92006-05-04 18:47:07 +000063Compiling programs for libmtp
64-----------------------------
65
66libmtp has support for the pkg-config script by adding a libmtp.pc
67entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
68"just" write:
69
70gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
71
72This also simplifies compilation using autoconf and pkg-config: just
73write e.g.
74
75PKG_CHECK_MODULES(MTP, libmtp)
76AC_SUBST(MTP_CFLAGS)
77AC_SUBST(MTP_LIBS)
78
79To have libmtp LIBS and CFLAGS defined. Needless to say, this will
80only work if you have pkgconfig installed on your system, but most
81people have nowadays.
82
83If your library is installed in e.g. /usr/local you may have to tell
84this to pkgconfig by setting the PKG_CONFIG_PATH thus:
85
86export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
87
88
89Documentation
90-------------
91
92Read the API documentation that can be generated with doxygen.
93It will be output in doc/html if you have Doxygen properly
94installed. (It will not be created unless you have Doxygen!)
95
96For information about the Media Transfer Protocol, see:
97http://en.wikipedia.org/wiki/Media_Transfer_Protocol
98
Linus Walleij7a83e552008-07-29 21:30:43 +000099The official 1.0 specification for MTP was released by the
100USB Implementers Forum in may, 2008. Prior to this, only a
101proprietary Microsoft version was available, and quite a few
102devices out there still use some aspects of the Microsoft
103version, which deviates from the specified standard. You can
104find the official specification here:
105http://www.usb.org/developers/devclass_docs/MTP_1.0.zip
Linus Walleij0dd71e92006-05-04 18:47:07 +0000106
Linus Walleij1b91ca62008-10-17 07:07:56 +0000107
108The Examples
109------------
110
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000111In the subdirectory "examples" you find a number of
Linus Walleij1b91ca62008-10-17 07:07:56 +0000112command-line tools, illustrating the use of libmtp in very
113simple terms.
114
115Please do not complain about the usability or documentation
116of these examples, they look like they do for two reasons:
117
1181. They are examples, not tools. If they were intended for
119 day-to-day usage by commandline freaks, I would have
120 called them "tools" not "examples".
121
1222. The MTP usage paradigm is that a daemon should hook
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000123 the device upon connection, and that it should be
Linus Walleij1b91ca62008-10-17 07:07:56 +0000124 released by unplugging. GUI tools utilizing HAL (hald)
125 and D-Bus do this much better than any commandline
126 program ever can. (See below on bugs.) Specificationwise
127 this is a bug, however it is present in many, many
128 devices.
129
130That said, if you want to pick up and maintain the examples,
131please volunteer.
132
133
Linus Walleijc36e2a62011-12-29 21:31:49 +0100134FAQ: Common Problems
135--------------------
136
137Some MTP devices have strange pecularities. We try to work around
138these whenever we can, sometimes we cannot work around it or we
139cannot test your solution.
140
Linus Walleij925acbe2012-11-13 21:37:40 +0100141* Android locked screen: some devices just report zero files
142 and no storages when the device screen is locked, it looks like
143 so:
144
145 mtp-detect
146 Device 0 (VID=04e8 and PID=6860) is a Samsung Galaxy models (MTP).
147 Attempting to connect device(s)
148 Error 1: Get Storage information failed.
149 Device: SHV-E210K
150 LIBMTP_Get_Storage(): No data available
151 OK.
152
153 This is probably so as not to allow the MTP access to be used
154 as a "backdoor" into the device. Unlock the device before listing
155 files, set the autolock to some large value or disabled if it
156 disturbs you, you are causing this to yourself, or should we say
157 that your vendor is prioritizing security and privacy over
158 ease-of-use. (You may talk to your vendor about this.)
159
Linus Walleijc36e2a62011-12-29 21:31:49 +0100160* mtp-* tools doesn't work because someone else is already hogging
161 the device
162
163 This is a common problem, the most common case could be that
164 gphoto2 (which can also talk PTP/MTP) is taking over the device
165 as soon as it's plugged in. Some distributions are configured that
166 way. Counter it like this:
167
168 gvfs-mount -s gphoto2
169
170 Then re-attach the device.
171
Linus Walleij5fff17e2012-07-18 23:49:05 +0200172 Sometimes the "gvfs-gphoto2-volume-monitor" is running on the
173 system and hogging the device, try something like:
174
Linus Walleijfb807262012-08-18 22:31:45 +0200175 pkill gfvs-gphoto2-volume-monitor
Linus Walleij5fff17e2012-07-18 23:49:05 +0200176
Linus Walleijfb807262012-08-18 22:31:45 +0200177 Then plug in the device and issue "mtp-detect" to figure out if
178 this may be the case.
Linus Walleij5fff17e2012-07-18 23:49:05 +0200179
Linus Walleijc36e2a62011-12-29 21:31:49 +0100180* Generic MTP/PTP disconnect misbehaviour: we have noticed that
181 Windows Media Player apparently never close the session to an MTP
182 device. There is a daemon in Windows that "hooks" the device
183 by opening a PTP session to any MTP device, whenever it is
184 plugged in. This daemon proxies any subsequent transactions
185 to/from the device and will never close the session, thus
186 Windows simply does not close sessions at all.
187
Linus Walleije962add2012-01-13 20:22:22 +0100188 For example this means that a device may work the first time
189 you run some command-line example like "mtp-detect" while
190 subsequent runs fail.
191
Linus Walleijc36e2a62011-12-29 21:31:49 +0100192 Typical sign of this illness: broken pipes on closing sessions,
193 on the main transfer pipes(s) or the interrupt pipe:
194
195 Closing session
196 usb_clear_halt() on INTERRUPT endpoint: Broken pipe
197 OK.
198
199 This means that device manufacturers doesn't notice any problems
200 with devices that do not correctly handle closing PTP/MTP
201 sessions, since Windows never do it. The proper way of closing
202 a session in Windows is to unplug the device, simply put.
203
204 Since libmtp actually tries to close sessions, some devices
205 may fail since the close session functionality has never been
206 properly tested, and "it works with Windows" is sort of the
207 testing criteria at some companies.
208
Linus Walleije962add2012-01-13 20:22:22 +0100209 You can get Windows-like behaviour on Linux by running a udev-aware
Linus Walleijc36e2a62011-12-29 21:31:49 +0100210 libmtp GUI client like Rhythmbox or Gnomad2, which will "hook"
211 the device when you plug it in, and "release" it if you unplug
Linus Walleije962add2012-01-13 20:22:22 +0100212 it, and you start/end you transfer sessions by plugging/unplugging
213 the USB cable.
214
215 The "Unix way" of running small programs that open the device,
216 do something, then close the device, isn't really working with
217 such devices and you cannot expect to have command line tools
218 like the mtp examples work with them. You could implement new
219 example programs that just call to a mediating daemon like the
220 Windows MTP stack does. (And change all programs using libmtp
221 directly today.)
Linus Walleijc36e2a62011-12-29 21:31:49 +0100222
223 If this bug in your device annoys you, contact your device
224 manufacturer and ask them to test their product with some libmtp
225 program.
226
Linus Walleijf776f7b2012-06-06 10:14:05 +0200227* Samsung Android 2.3.x devices: these have a special MTP stack
228 with some specific bugs that we have maybe nailed down now.
229 It suffers from an "immediate connect" syndrome, i.e. you have
230 to connect to the device within 7 seconds of plugging in, or it
231 will go numb. This also goes for command-line activity with
232 the example programs, so this device is better used with a
233 GUI tool like Rhythmbox, gnomad2...
234
Linus Walleijc36e2a62011-12-29 21:31:49 +0100235* Generic USB misbehaviour: some devices behave badly under MTP
236 and USB mass storage alike, even down to the lowest layers
237 of USB. You can always discuss such issues at the linux-usb
238 mailing list if you're using Linux:
239 http://www.linux-usb.org/mailing.html
240
241 If you have a problem specific to USB mass storage mode, there
242 is a list of strange behaving devices in the Linux kernel:
243 http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h
244 You can discuss this too on the mentioned list, for understanding
245 the quirks, see:
246 http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt
247
248* Generic certificate misbehaviour. All devices are actually
249 required to support a device certificate to be able to
250 encrypt Windows Media (WMA/WMV) files. However there are
251 obviously a lot of devices out there which doesn't support
252 this at all but instead crash. Typical printout:
253
254 Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed
255 to get unicode property.
256
257 This should only affect "mtp-detect", there is no other
258 application currently retrieveing the certificate (not that we
259 know anyway).
260
261* Kernel bug on Linux. Linux 2.6.16 is generally speaking required
262 to use any MTP device under USB 2.0. This is because the EHCI
263 driver previously did not support zero-length writes to endpoints.
264 It should work in most cases however, or if you connect it
265 to an UHCI/OHCI port instead (yielding lower speed). But
266 please just use a recent kernel.
267
268* Zen models AVI file seeking problem: the Zens cannot parse the
269 files for the runlength metadata. Do not transfer file with e.g.
270 mtp-sendfile, use mtp-sendtr and set the length of the track to
271 the apropriate number of seconds and it will work. In graphical
272 clients, use a "track transfer" function to send these AVI files,
273 the Zens need the metadata associated with tracks to play back
274 movies properly. Movies are considered "tracks" in the MTP world.
275
276* Some devices that disregard the metadata sent with the MTP
277 commands will parse the files for e.g. ID3 metadata. Some still
278 of these devices expect only ID3v2.3 metadata and will fail with
279 a modern ID3v2,4 tag writer, like many of those found in Linux
280 applications. Windows Media Player use ID3v2.3 only, so many
281 manufacturers only test this version.
282
283* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
284 that makes it drop the last two characters off a playlist name.
285 It is fixed in later firmware.
286
287* For Creative Technology devices, there are hard limits on how
288 many files can be put onto the device. For a 30 GiB device (like
289 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
290 is 15000 files. For further Creative pecularities, see the
291 FAQ sections at www.nomadness.net.
292
293* Sandisk sansa c150 and probably several other Sandisk devices
294 (and possibly devices from other manufacturers) have a dual
295 mode with MTP and USB mass storage. The device will initially
296 claim to be mass storage so udev will capture is and make the
297 use of MTP mode impossible. One way of avoiding it could be to
298 be to blacklist the "usb-storage" module in
299 /etc/modprobe.c/blacklist with a row like this:
300 "blacklist usb-storage". Some have even removed the
301 "usb-storage.ko" (kernel module file) to avoid loading.
302
303* Sandisk Sansa Fuze has three modes: auto, MTP or mass storage
304 (MSC). Please set it to MTP to avoid problems with libmtp.
305
306* The iriver devices (possibly all of them) cannot handle the
307 enhanced GetObjectPropList MTP command (0x9805) properly. So
308 they have been banned from using it.
309
310* iriver devices have problems with older versions of libmtp and
311 with new devices libmtp does not know of as of yet, since it
312 has an oldstyle USB device controller that cannot handle zero
313 writes. (Register your device with us!) All their devices are
314 likely to need a special device flag in the src/libusb-glue.c
315 database.
316
317* The Samsung Yepp T9 has several strange characteristics, some
318 that we've managed to work around. (For example it will return
319 multiple PTP packages in a single transaction.)
320
321* The early firmware for Philips HDD players is known to be
322 problematic. Please upgrade to as new firmware as you can get.
323 (Yes this requires some kind of Windows Installation I think.)
324
325* Philips HDD 1630/16 or 1630/17 etc may lock themselves up,
326 turning inresponsive due to internal corruption. This typically
327 gives an error in opening the PTP session. Apparently you can
328 do a "repair" with the firmware utility (Windows only) which
329 will often fix this problem and make the device responsive
330 again.
331
332* Some devices that implement GetObjectPropList (0x9805) will
333 not return the entire object list if you request a list for object
334 0xffffffffu. (But they should.) So they may need the special
335 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
336
337* Some (smaller) subset of devices cannot even get all the
338 properties for a single object in one go, these need the
339 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
340 iriver devices seem to have this bug.
341
342* The Toshiba Gigabeat S (and probably its sibling the
343 Microsoft Zune and other Toshiba devices) will only display
344 album information tags for a song in case there is also
345 an abstract album (created with the album interface) with
346 the exact same name.
347
348* The Zen Vision:M has an older firmware which is very corrupt,
349 it is incompatible with the Linux USB stack altogether. The
350 kernel dmesg will look something like this, and you have to
351 upgrade the firmware using Windows:
352 usb 4-5: new high speed USB device using ehci_hcd and address 5
353 usb 4-5: configuration #1 chosen from 1 choice
354 usb 4-5: can't set config #1, error -110
355
356* The Sirus Stiletto does not seem to allow you to copy any files
357 off the device. This may be someone's idea of copy protection.
358
359* The Samsung P2 assigns parent folder ID 0 to all unknown file
360 types.(i.e. moves them to the root folder)
361
362* The Sandisk Sansa Clip+ needs a firmware upgrade in earlier
363 versions in order to work properly.
364
365
Linus Walleija1b66f22007-05-10 20:02:16 +0000366New Devices
367-----------
368
Linus Walleijfcf88912006-06-05 13:23:33 +0000369If you happen upon a device which libmtp claims it cannot
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000370autodetect, please submit the vendor ID and device ID
Linus Walleij9ee29402007-10-31 20:24:48 +0000371(these can be obtained from the "lsusb" and "lsusb -n"
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000372commands run as root) as a bug, patch or feature request
373on the Sourceforge bug tracker at our homepage. If it
374gives a sensible output from "mtp-detect" then please attach
375the result as well as it teach us some stuff about your
376device. If you've done some additional hacking, join our
Linus Walleij9ee29402007-10-31 20:24:48 +0000377mailinglist and post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +0000378
Linus Walleija1b66f22007-05-10 20:02:16 +0000379If you want to be able to hack some more and you're not
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000380afraid of C hacking, add an entry for your device's
381vendor/product ID and a descriptive string to the database
Linus Walleij6dc01682007-11-15 21:23:46 +0000382in the file src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000383
384If you want to poke around to see if your device has some
385special pecularities, you can test some special device
Linus Walleij6dc01682007-11-15 21:23:46 +0000386flags (defined in src/device-flags.h) by inserting them
387together with your device entry in src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000388Flags can be tested in isolation or catenated with "|"
389(binary OR). If relatives to your device use a certain
390flag, chances are high that a new device will need it
391too, typically from the same manufacturer.
392
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000393The most common flag that needs to be set is the
Linus Walleija1b66f22007-05-10 20:02:16 +0000394DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
395drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000396MTP access impossible. This is however not expected to
397really work: this is a problem being tracked as of
398now (2007-08-04). See the "last resort" solutions below
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000399if you really need to get your dual-mode device to work
Linus Walleij94f23d52007-08-04 19:37:28 +0000400with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000401
Linus Walleijcc2cf972007-11-22 20:23:43 +0000402Another flag which is easy to identify is the
403DEVICE_FLAG_NO_ZERO_READS, which remedies connection
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000404timeouts when getting files, and some timeouts on e.g.
Linus Walleijcc2cf972007-11-22 20:23:43 +0000405successive "mtp-connect" calls.
406
Linus Walleija1b66f22007-05-10 20:02:16 +0000407If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000408works under Windows, so we enjoy reading USB packet sniffs
409that reveal the low-level traffic carried out between
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000410Windows Media Player and your device. This can be done
Linus Walleij61c25682007-09-04 14:46:21 +0000411using e.g.:
412
413* USBsnoop:
414 http://benoit.papillault.free.fr/usbsnoop/
415
416* The trial version of HHD Softwares software-only
417 USB monitor. You need to get a copy of version 2.37 since
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000418 the newer trial versions won't let you carry out the
Linus Walleij61c25682007-09-04 14:46:21 +0000419 needed packet sniffs. (As of 2007-03-10 a copy can be found
420 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
421
Linus Walleijda558be2007-03-10 21:42:25 +0000422There are other USB monitors as well, some more expensive
423alternatives use hardware and even measure electronic
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000424characteristics of the traffic (which is far too much
Linus Walleijda558be2007-03-10 21:42:25 +0000425detail for us).
426
Linus Walleij91fb0282007-09-03 21:16:08 +0000427Device sniffs are an easy read since the PTP/MTP protocol
428is nicely structured. All commands will have a structure such
429as this in the log, we examplify with a object list request:
430
431PTP REQEUST:
432000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
433Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
434Send 0x20 bytes to the device:
435 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
436 Length TYPE CMD Trans# Param1
437
438 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
439 Param2 Param3 Param4 Param5
440
441[OPTIONAL] DATA PHASE:
442000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
443Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
444Get 0x1a bytes from the device:
445 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
446 Length TYPE CMD Trans# DATA
447
448 27 03 00 10 02 DC 04 00 00 30 '....Ü...0
449
450RESPONSE:
451000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
452Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
453Get 0xc bytes from the device:
454 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
455 Length TYPE CODE Trans#
456
457* One send (OUT to the device), two reads (IN from the device).
458
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000459* All three byte chunks commands are
460 sent/recieved/recieeved by the function ptp_transaction()
Linus Walleij91fb0282007-09-03 21:16:08 +0000461 in the file ptp.c.
462
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000463* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
464 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
Linus Walleij91fb0282007-09-03 21:16:08 +0000465 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
466 are ALWAYS called. The TYPE field correspond to this, so the
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000467 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
Linus Walleij91fb0282007-09-03 21:16:08 +0000468 and "RESPONSE" (0x0003).
469
470* Notice that the byte order is little endian, so you need to read
471 each field from right to left.
472
473* This COMMAND has:
474 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
475 Transaction# 0x00000023.
476 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
477 0x00000000, in this case it means "get props for object 0x10000327",
478 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
479 parameters that are always zero (no idea what they mean or their
480 use).
481
482* The DATA has:
483 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
484 Transaction# 0x00000023.
485 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
486 Which means in this case, (and this is the tricky part) "here
487 you have 1 property", "for object 0x10000327", "it is property
488 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
489 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
490 is perfectly valid to have undefined object formats, since it
491 is a legal value defining this).
492
493* This RESPONSE has:
494 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
495 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000496 Transaction# 0x00000023.
Linus Walleijfcf88912006-06-05 13:23:33 +0000497
Linus Walleijd05fce62007-09-29 20:17:23 +0000498If you want to compare the Windows behaviour with a similar
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000499operation using libmtp you can go into the src/libusb-glue.c
Linus Walleij6dc01682007-11-15 21:23:46 +0000500file and uncomment the row that reads:
Linus Walleijd05fce62007-09-29 20:17:23 +0000501
502//#define ENABLE_USB_BULK_DEBUG
503
504(I.e. remove the two //.)
505
506This will make libmtp print out a hex dump of every bulk USB
507transaction. The bulk transactions contain all the PTP/MTP layer
508data, which is usually where the problems appear.
509
Linus Walleij6fd2f082006-03-28 07:19:22 +0000510
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200511Notes to assist with debugging new devices:
512-------------------------------------------
513
Linus Walleijc36e2a62011-12-29 21:31:49 +0100514In debugging new hardware, we highly recommend that you only
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200515use the example mtp-* applications that come with libmtp, as other
516applications may have their own bugs that may interfere with your
517new device working correctly. Using another application instead of
518those that come with libmtp just adds another point of failure.
519
520For debugging, there are 3 main options:
521
Linus Walleijc36e2a62011-12-29 21:31:49 +01005221. Use the env variable: LIBMTP_DEBUG to increase the
523verboseness of the debugging output for any application using
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200524libmtp. Relevant codes are:
525* 0x00 [0000 0000] : no debug (default)
526* 0x01 [0000 0001] : PTP debug
527* 0x02 [0000 0010] : Playlist debug
528* 0x04 [0000 0100] : USB debug
529* 0x08 [0000 1000] : USB data debug
530// Codes are hex and binary respectively. Simple add them togther
531// to get your desired level of output.
532
533(Assuming bash)
Linus Walleijc36e2a62011-12-29 21:31:49 +0100534eg:
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200535$ export LIBMTP_DEBUG=12
536$ mtp-detect
537 // To get USB debug and USB data debug information.
538
539$ export LIBMTP_DEBUG=2
540$ mtp-detect
541 // To get Playlist debug information.
Linus Walleijc36e2a62011-12-29 21:31:49 +0100542
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200543Also note, an application may also use the LIBMTP_debug() API
544function to achieve the same options as listed above.
545
Linus Walleijc36e2a62011-12-29 21:31:49 +01005462. Use "strace" on the various mtp-* commands to see where/what
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200547is falling over or getting stuck at.
548* On Solaris and FreeBSD, use "truss" or "dtrace" instead on "strace".
549* On Mac OS X, use "ktrace" or "dtrace" instead of "strace".
550* On OpenBSD and NetBSD, use "ktrace" instead of "strace".
551
552This will at least help pinpoint where the application is failing, or
Linus Walleijc36e2a62011-12-29 21:31:49 +0100553a device is reporting incorrect information. (This is extremely helpful
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200554with devices that have odd disconnection requirements).
555
Linus Walleijc36e2a62011-12-29 21:31:49 +0100556The use of these tools may also pinpoint issues with libusb as
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200557implemented by each OS vendor or issues with the MTP implementation
558on the new device as well, so please be prepared for either case.
559
5603. Use "gdb" or similar debugger to step through the code as it is
561run. This is time consuming, and not needed just to pinpoint where
Linus Walleijc36e2a62011-12-29 21:31:49 +0100562the fault is.
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200563
Linus Walleijc36e2a62011-12-29 21:31:49 +0100564The use of gdb or another debugger may also miss or actually cause
565command and data timing issues with some devices, leading to false
Darran Kartaschewa476ae92011-08-08 09:07:30 +0200566information. So please consider this a last resort option.
567
568Also please read the "It's Not Our Bug!" section below, as it does
569contain some useful information that may assist with your device.
570
571
Linus Walleij8d799eb2009-07-23 22:58:06 +0000572Dual-mode devices does not work - last resort:
573----------------------------------------------
Linus Walleijbd7624c2007-05-28 10:48:54 +0000574
575Some devices that are dual-mode are simply impossible to get
576to work under Linux because the usb-storage(.ko) kernel
577module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000578when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
579it DOES release it but the device will immediately be probed
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000580at the USB mass storage interface AGAIN because it
Linus Walleij94f23d52007-08-04 19:37:28 +0000581enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000582
Linus Walleij8d799eb2009-07-23 22:58:06 +0000583Here is what some people do:
584
585 1. Plug in the device.
586 2. USB-mass storage folder will open automatically.
587 3. Unmount the device.
588 4. Run mtp-detect. It will most likely fail the first time.
589 5. Run mtp-detect again, it might work this time, or fail. Keep running
590 till it works. 99% it works by the third try.
591 6. Once mtp-detect gives you an "Ok", open either Rhythmbox or Gnomad2,
592 everything should work.
593
Linus Walleij1b9f1642013-07-07 22:57:23 +0200594Linux: Try this, if you have a recent Linux kernel,
595add the file (as root):
596
597/etc/modprobe.d/no-usb-storage.conf
598
599With the contents:
600
601options usb-storage quirks=1234:4321:i
602
603This will tell usb-storage to ignore this device when it's inserted
604so it is not hogged by the mass storage interfaces. Remove and re-insert
605the device and see if it works. Usually this does the trick.
606
607For older systems, or as a bigger hammer, run (as root) something
608like:
Linus Walleij584eb8d2007-09-05 19:51:27 +0000609
610> rmmod usb_storage ; mtp-detect
611
612You can run most any command or a client like gnomad2 or
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000613Amarok immediately after the rmmod command. This works
Linus Walleij1b9f1642013-07-07 22:57:23 +0200614sometimes. Another even more brutal approach is this:
Linus Walleijbd7624c2007-05-28 10:48:54 +0000615
Linus Walleij94f23d52007-08-04 19:37:28 +0000616* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000617* Add the line "blacklist usb-storage"
Linus Walleijbd7624c2007-05-28 10:48:54 +0000618* Reboot.
619
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000620Now none of you USB disks, flash memory sticks etc will be
Linus Walleijbd7624c2007-05-28 10:48:54 +0000621working (you just disabled them all). However you *can* try
622your device, and it might have started working because there
623is no longer a USB mass storage driver that tries to hook onto
624the mass storage interface of your device.
625
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000626If not even blacklisting works (check with
Linus Walleij94f23d52007-08-04 19:37:28 +0000627"lsmod | grep usb-storage"), there is some problem with
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000628something else and you may need to remove or rename the file
Linus Walleij94f23d52007-08-04 19:37:28 +0000629/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
630manually.
631
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000632If you find the PerfectSolution(TM) to this dilemma, so you
Linus Walleijbd7624c2007-05-28 10:48:54 +0000633can properly switch for individual devices whether to use it
634as USB mass storage or not, please tell us how you did it. We
635know we cannot use udev, because udev is called after-the-fact:
636the device is already configured for USB mass storage when
637udev is called.
638
Linus Walleije20abaf2007-12-10 11:20:34 +0000639On Mac OS there is another ugly hack:
640
6411. Open up a terminal window
6422. Type:
643sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
644/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
645
646and when prompted enter your password.
647
6483. Restart.
649
650To reverse this change, just reverse the filenames:
651
652sudo mv /System/Library/Extensions/
653IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
654IOUSBMassStorageClass.kext
655
656and restart.
657
Linus Walleijbd7624c2007-05-28 10:48:54 +0000658
Linus Walleij15def332006-09-19 14:27:02 +0000659Calendar and contact support:
660-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000661
Linus Walleij3c16fe42006-04-30 07:53:41 +0000662The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000663and VCard (.vcf) files from programs like for example
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000664Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000665
Linus Walleij3c16fe42006-04-30 07:53:41 +0000666- The file must be in DOS (CR/LF) format, use the unix2dos
667 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000668
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000669- Repeat events in calendar files do not seem to be supported,
Linus Walleij15def332006-09-19 14:27:02 +0000670 entries will only appear once.
671
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000672- Calendar (.ics) files should be stored in the folder "My Organizer"
Linus Walleij15def332006-09-19 14:27:02 +0000673 when sent to the device (this directory should be autodetected
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000674 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000675 -f "My Organizer" to sendfile for this) Apparently this file can
676 also contain tasklists.
677
678- Contact (.vcf) files should be stored in the folder "My Contacts"
679 when sent to the device. (-f "My Contacts")
680
681- Some devices are picky about the name of the calendar and
682 contact files. For example the Zen Microphoto wants:
683
Linus Walleijb1318d12006-09-25 14:59:26 +0000684 Calendar: My Organizer/6651416.ics
685 Contacts: My Organizer/6651416.vcf
686
687
688Syncing in with Evolution and Creative Devices
689----------------------------------------------
690
691Evolution can easily export .ics an .vcf files, but you currently
692need some command-line hacking to get you stuff copied over in
693one direction host -> device. The examples/ directory contains a script
694created for the Creative Zen Microphoto by Nicolas Tetreault.
695
Linus Walleij6e8cef42006-12-03 20:45:04 +0000696
Linus Walleijd132d8e2007-04-03 23:24:54 +0000697Lost symbols
698------------
699
700Shared libraries can be troublesome to users not experienced with
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000701them. The following is a condensed version of a generic question
Linus Walleijd132d8e2007-04-03 23:24:54 +0000702that has appeared on the libmtp mailing list from time to time.
703
704> PTP: Opening session
705> Queried Creative Zen Vision:M
706> gnomad2: relocation error: gnomad2: undefined symbol:
707> LIBMTP_Get_Storageinfo
708> (...)
709> Are these type of errors related to libmtp or something else?
710
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000711The problem is of a generic nature, and related to dynamic library
Linus Walleijd132d8e2007-04-03 23:24:54 +0000712loading. It is colloquially known as "dependency hell".
713(http://en.wikipedia.org/wiki/Dependency_hell)
714
715The gnomad2 application calls upon the dynamic linker in Linux to
716resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
717(ELF symbol, or link point or whatever you want to call them, a
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000718symbol is a label on a memory address that the linker shall
Linus Walleijd132d8e2007-04-03 23:24:54 +0000719resolve from label to actual address.)
720For generic information on this subject see the INSTALL file and
721this Wikipedia page:
722
723http://en.wikipedia.org/wiki/Library_(computing)
724
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000725When Linux /lib/ld-linux.so.X is called to link the symbols compiled
726into gnomad2 (or any other executable using libmtp), it examines the
727ELF file for the libmtp.so.X file it finds first and cannot resolve
Linus Walleijd132d8e2007-04-03 23:24:54 +0000728the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000729problem witj) from it, since it's probably not there. There are many
Linus Walleijd132d8e2007-04-03 23:24:54 +0000730possible causes of this symbol breakage:
731
7321) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
733 whatever) that do not match up. Typical cause: your gnomad2 package was
734 built against a newer version of libmtp than what's installed on your
735 machine. Another typical cause: you installed a package you found on
736 the web, somewhere, the dependency resolution system did not protest
737 properly (as it should) or you forced it to install anyway, ignoring
738 some warnings.
739
7402) You compiled libmtp and/or gnomad2 from source, installing both or
741 either in /usr/local/lib and /usr/local/bin. This means at compile-time
742 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
743 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
744 order to resolve the symbols. This loader will look into the file
745 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
746 paths to libraries to be used for resolving the symbols. If you have
747 some older version of libmtp in e.g. /usr/lib (typically installed by a
748 package manager) it will take precedence over the new version you just
749 installed in /usr/local/lib and the newly compiled library in
750 /usr/local/lib will *not* be used, resulting in this error message.
751
7523) You really did install the very latest versions (as of writing libmtp
753 0.1.5 and gnomad2 2.8.11) from source and there really is no
754 pre-installed package of either on your machine. In that case I'm
755 totally lost, I have no idea what's causing this.
756
757Typical remedies:
758
7591) If you don't want to mess around with your system and risk these
760 situations, only use pre-packaged software that came with the
761 distribution or its official support channels. If it still breaks,
762 blame your distribution, they're not packaging correctly. Relying on
763 properly packaged software and not installing things yourself *is* the
764 Linux solution to the "dependency hell" problem.
765
7662) Read about dynamically linked library handling until the stuff I wrote
767 about in the previous list sounds like music to your ears, inspect
768 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
769 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
770 YaST or whatever your distribution uses, compile libmtp and gnomad2
771 (or whatever) from source only and you will be enlighted.
772
773I don't know if this helps you, it's the best answer we can give.
Linus Walleij387e37a2008-10-29 17:22:22 +0000774
775
776API is obscure - I want plain files!
777------------------------------------
778
779PTP/MTP devices does not actually contain "files", they contain
780objects. These objects have file names, but that is actually
781just a name tag on the object.
782
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000783Folders/directories aren't really such entities: they are just
Linus Walleij387e37a2008-10-29 17:22:22 +0000784objects too, albeit objects that can act as parent to other
Linus Walleij8aba06d2008-12-28 08:26:57 +0000785objects. They are called "associations" and are created in atomic
Linus Walleij387e37a2008-10-29 17:22:22 +0000786fashion and even though there is an MTP command to get all the
Linus Walleij514e2eb2012-09-02 16:55:45 +0200787associations of a certain object, this command is optional
Linus Walleij8aba06d2008-12-28 08:26:57 +0000788so it is perfectly possible (and most common, actually) to create
789devices where the "folders" (which are actually associations) have
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000790no idea whatsoever of what files they are associated as parents to
Linus Walleij387e37a2008-10-29 17:22:22 +0000791(i.e. which files they contain). This is very easy for device
Linus Walleij8aba06d2008-12-28 08:26:57 +0000792manufacturers to implement, all the association (i.e. finding out
793which files are in a certain folder) has to be done by the MTP
794Initiator / host computer.
Linus Walleij387e37a2008-10-29 17:22:22 +0000795
796Moving a file to a new folder is for example very simple in a
797"real" file system. In PTP/MTP devices it is often not even possible,
Linus Walleij514e2eb2012-09-02 16:55:45 +0200798some devices *may* be able to do that, if they support command
7990x1019 "Move Object", but actually the only reliable way of executing
800file movement is to upload the file to the host, download it with
801the new parent, then delete the old file. We have played with the
802idea of implementing this time consuming function as a fallback
803in case the device does not support command 0x1019, perhaps one day
804we will do that. (Some devices also support command 0x101a
805"Copy Object".)
Linus Walleij387e37a2008-10-29 17:22:22 +0000806
Linus Walleij8aba06d2008-12-28 08:26:57 +0000807Then the issue that in PTP/MTP it is legal for two files to have
808exactly the same path as long as their object IDs differ. A
809folder/association can contain two files with the exact same name.
810(And on the Creative devices this even works, too, though most devices
811implicitly fail at this.) Perhaps one could add some custom hook for
812handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something
813similar, but it's really a bit kludgy.
814
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000815Playlists and albums aren't really files, thinking about
Linus Walleij387e37a2008-10-29 17:22:22 +0000816them as files like the hacks in libgphoto2 is really backwards. They are
817called associations and are more like a symbolic link that links in a
818star-shaped pattern to all the files that are part of the album/playlist.
819Some devices (Samsung) thought that was too complicated and have a
820different way of storing playlists in an UTF-16 encoded .spl-like file
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000821instead! This is why playlists/albums must have their own structs and
Linus Walleij387e37a2008-10-29 17:22:22 +0000822functions.
823
Linus Walleij8aba06d2008-12-28 08:26:57 +0000824Plain file access also assumes to be able to write files of an
825undetermined size, which is simply not possible in a transactional
826file system like PTP/MTP. (See further below.)
827
Linus Walleij387e37a2008-10-29 17:22:22 +0000828
829I Want Streaming!
830-----------------
831
832Streaming reads is easy. Just connect the output file descriptor from
833LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)
834wherever you want.
835
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000836People have connected this to TCP sockets for streaming web servers
837etc, works like a charm. Some devices will even survive if the callback
Linus Walleij387e37a2008-10-29 17:22:22 +0000838functions return non-zero and cancel the download. Some devices will
839lock up and even require a reset if you do that. Devices are poorly
840implemented so that's life. If you want to stream off a device, the
841best idea is always to stream the entire file and discard the stuff
842at the end you don't want. It will incur a delay if you e.g. want to
843skip between tracks, sadly.
844
845Then we get to the complicated things: streaming WRITES...
846
847There is a function:
848LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks)
849which will write a file to a device from a file descriptor, which may
850be a socket or whatever.
851
852HOWEVER: this requires a piece of metadata with the .filesize properly
853set first.
854
855This is not because we think it is funny to require that, the protocol
856requires it. The reason is that PTP/MTP is a transactional file system
857and it wants to be able to deny file transfer if the file won't fit on
858the device, so the transaction never even starts, it's impossible to
859start a transaction without giving file length.
860
861People really want streaming so I tried a lot of hacks to see if they
862would work, such as setting file size to 0xffffffffU or something other
863unnaturally big and then aborting the file transfer when the stream ends.
864It doesn't work: either the device crashes or the file simply disappears
865since the device rolls back all failed transactions.
866
867So this is an inherent limitation of the PTP/MTP protocol.
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000868
869
Linus Walleijae890212012-02-16 01:56:19 +0100870I want to remote control my device!
871-----------------------------------
872
873I have both good and bad news for you.
874
875The good news is that the MTP protocol has well-defined commands to play
876back content on a device. Operation 0xD411 (PTP_DPC_MTP_PlaybackObject)
877will start playing back a file on the device (whatever that may mean if
878this is not a music or video file), and operation 0xD403 can set the
879playback volume to save your ears. Then there are operations to
880determine how far into the current file you currently are, so as to
881support say progress bars.
882
883Since these commands have been around since the dawn of the MTP protocol
884and since it was developed in cooperation with Creative Technology, this
885is probably a requested feature from the Creative people who already had
886support for playback on their devices using the PDE protocol back then.
887
888Anyway, here are the bad news:
889[logs]$ grep d411 *
890mtp-detect-trekstor-vibez.txt: 0xd411: Playback Object
891
892Aha there is only one known device in the world which actually supports
893playback on the device. So either you go buy the Trekstor Vibez, or you
894can forget about this. You could always try asking your hardware vendor
895of choice to go implement this.
896
897Since none of the core developers of libmtp has the Trekstor device, this
898is not yet implemented in libmtp.
899
900
Linus Walleijbe8b03b2009-10-16 21:19:35 +0000901I make MTP devices!
902-------------------
903
904If you are a device vendor there is a lot you can do for libmtp:
905
906* Please consider assigning one of your employees as a contact person
907 for libmtp, have them sign up to the libmtp development list and answer
908 questions and post new device ID:s as they are released to our
909 mailing list.
910
911* If you want to help even more, assign someone to look deeper into
912 error reports on your specific devices, understand why your firmware
913 may require some special device flags and what can be done about it.
914
915* Do you have spare devices you can give us? Send them to Richard (Mac
916 support) or Linus (Linux support). (So far nobody did that except for
917 Microsoft who sent us a Zune by proxy!)
918
919Vendors do need help from libmtp too, especially we want to help
920vendors improve their MTP stacks, because they all suffer from the
921same problem: the lack of a proper conformance test has made many devices
922incompliant with the MTP specification as it is published today: most
923devices are just compliant with the Windows MTP stack, and don't work
924out-of-the-box with libmtp. We need someone on the inside to help in
925bug reporting vendors MTP stacks internally so these issues are raised.
926A good way to go toward better MTP compliance is to test with an
927alternative implementation of the stack. In e.g. IETF standardization
928it is compulsory for an RFC to have atleast two independent implementations
929for it to reach the status as standard.
930
931Being compliant with libmtp is also more and more important for
932vendors: libmtp is being deployed in some embedded systems like
933set-top-boxes etc. It will be very irritating for customers if a device
934will not dock properly with some home entertainment equipment just because
935it is based on Linux and libmtp and not the Windows MTP stack.
Linus Walleij5f5c69f2011-06-26 14:34:13 +0200936
937Autodetect with gudev
938---------------------
939
940Previously you would use HAL to detect devices being plugged in. Nowadays
941we use udev directly, or though the GNOME libgudev library. LIBMTPs
942default udev rules export the proper properties to detect any MTP device
943automatically, here is a verbose example derived from gnomad2:
944
945#define G_UDEV_API_IS_SUBJECT_TO_CHANGE
946#include <gudev/gudev.h>
947const char * const gudev_subsystems[] = { "usb", NULL };
948GUdevClient *gudev_client;
949guint uevent_id;
950guint uevent_bus_hooked = 0;
951guint uevent_device_hooked = 0;
952
953
954static void uevent_cb(GUdevClient *client, const char *action, GUdevDevice *device, void *data)
955{
956 guint64 devicenum;
957 guint vendor;
958 guint model;
959 guint busnum;
960 guint devnum;
961 guint mtpdevice;
962
963 devicenum = (guint64) g_udev_device_get_device_number(device);
964 g_print("%s event for %s (%"G_GINT64_MODIFIER"x)", action,
965 g_udev_device_get_sysfs_path (device), devicenum);
966
967 /* get device info */
968 vendor = get_property_as_int(device, "ID_VENDOR_ID", 16);
969 model = get_property_as_int(device, "ID_MODEL_ID", 16);
970 busnum = get_property_as_int(device, "BUSNUM", 10);
971 devnum = get_property_as_int(device, "DEVNUM", 10);
972 mtpdevice = get_property_as_int(device, "ID_MTP_DEVICE", 10);
973
974 if (vendor == 0 || model == 0) {
975 g_print("couldn't get vendor or model ID for device at (%x:%x)\n",
976 busnum, devnum);
977 return;
978 } else {
979 g_print("vendor = %x, model = %x, bus = %x, device = %x\n",
980 vendor, model, busnum, devnum);
981 }
982
983 if (mtpdevice) {
984 g_print("device is MTP compliant\n");
985
986 if (g_str_equal(action, "add") &&
987 uevent_bus_hooked == 0 &&
988 uevent_device_hooked == 0) {
989 g_print(MTP device plugged in!\n");
990 uevent_bus_hooked = busnum;
991 uevent_device_hooked = devnum;
992 scan_jukebox(NULL);
993 } else if (g_str_equal (action, "remove") &&
994 uevent_bus_hooked == busnum &&
995 uevent_device_hooked == devnum) {
996 g_print("MTP device removed!\n");
997 uevent_bus_hooked = 0;
998 uevent_device_hooked = 0;
999 }
1000 }
1001}
1002
1003
1004
1005(...)
1006 /*
1007 * Monitor udev device events - we're only really interested in events
1008 * for USB devices.
1009 */
1010 gudev_client = g_udev_client_new(gudev_subsystems);
1011 uevent_id = g_signal_connect_object(gudev_client,
1012 "uevent",
1013 G_CALLBACK(uevent_cb),
1014 NULL, 0);
Linus Walleij187ac2f2012-05-02 19:08:03 +02001015
1016SKETCH OF AN OVERVIEW
1017---------------------
1018
1019Draft agenda for a talk on MTP devices submitted for the Android
1020builders summit, might come to recycle this:
1021
1022- Protocol overview
Linus Walleijb35c1132012-09-03 07:45:30 +02001023 - Transactional filesystem - no corruption due to unplugged cables!
Linus Walleijfd9132c2013-03-05 10:43:49 +01001024 - The host and the device can access the files simultaneously, the
1025 device will always "own" the physical file system and proxy the
1026 host (MTP initiator).
Linus Walleij187ac2f2012-05-02 19:08:03 +02001027- libmtp interface
1028- relation to libgphoto2
Linus Walleijb35c1132012-09-03 07:45:30 +02001029- User expectations fall short:
1030 - Not really a mountable filesystem.
1031 - Streaming does not work. (Size needs to be known beforehand due to
1032 transactional nature.)
Linus Walleijfd9132c2013-03-05 10:43:49 +01001033 - GVFS MTP backend to the rescue.
Linus Walleij187ac2f2012-05-02 19:08:03 +02001034- Device sins
1035 - Android bugs
1036 - Samsungs special Android MTP stack
1037 - SonyEricsson Aricent stack for Xperia Androids pre 4.0, broken headers!
Linus Walleij6bc5d262012-09-02 17:45:42 +02001038 - Flat access model vs hierarchical, how Android uses MTP as an hierachical
1039 file system while it was previously a flat database.
Linus Walleijfd9132c2013-03-05 10:43:49 +01001040 - Old paradigm: scan the entire non-hierarchical storage for all content,
1041 build a cache to speed up the (USB 1.1!) link. Usually all files were
1042 stored in the root folder or a single folder named "/Music" or similar.
1043 - Android introduced deeply nested folder hierarchies, not seen before
1044 on MTP devices.
1045 - Microsoft not using the complete metadata dump feature of the MTP
1046 protocol (once introduced by creative) instead they walk directories
1047 separately.
1048 - So caching a big device will take long time and/or timeout.
1049 - Go-MTPFS (FUSE) and GVFS MTP - doing the partial directory walk rather
1050 than caching all files.
Linus Walleij40397102013-04-29 11:38:03 +02001051 - Especially Android devices nowadays assume that
1052 you want to index a folder at the time, whereas older MTP devices (such
1053 as those from Creative) would assume that you wanted to index the entire
1054 device as it was plugged in, and device firmware is now ever more tailored
1055 toward per-folder filetree walking. This makes it harder for the library
1056 to provide the right abstractions: do we provide an API for indexing the
1057 whole device which is unacceptably slow on new devices, or do we provide
1058 an API for indexing a directory at the time which will somehow work on
1059 older devices too? Shall we deprecate the older API?
Linus Walleij187ac2f2012-05-02 19:08:03 +02001060- Detecting from vendor extension, can fix in newer extensions!
1061- Autoprobing on Linux
1062 - Color devices do not like autoprobing
Linus Walleij7237d6a2012-08-18 22:50:21 +02001063 - Devices need different PIDs for every alternative interface due to
1064 the Windows USB stack.
Linus Walleijb35c1132012-09-03 07:45:30 +02001065 - Multimode USB - one PID for each mode due to Windows limitations not
1066 applicable to Linux, SONY devices have ~5 different PIDs for a single
1067 device.
Linus Walleijfd9132c2013-03-05 10:43:49 +01001068 - Mode switch devices? Maybe we do this wrong.
1069- MTPZ, came and went. Apparently deprecated by Microsoft with Windows
1070 Phone 8.
Linus Walleijb35c1132012-09-03 07:45:30 +02001071- Ideas??
1072