blob: 8f76f26676a7ff4a9a7f1fff494b32905a9bf596 [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
7Heritage
8--------
9
10libmtp is based on several ancestors:
11
12* libptp2 by Mariusz Woloszyn was the starting point used
13 by Richard A. Low for the initial starter port. You can
14 find it at http://libptp.sourceforge.net/
15
16* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
17 used at a later stage since it was (is) more actively
18 maintained. libmtp tracks the PTP implementation in
19 libgphoto2 and considers it an upstream project. We will
20 try to submit anything generally useful back to libgphoto2
21 and not make double efforts. In practice this means we
22 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
23 source code. If you need to change things in these files,
24 make sure it is so general that libgphoto2 will want to
25 merge it to their codebase too. You find libgphoto2 as part
26 of gPhoto: http://gphoto.sourceforge.net/
27
28* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000029 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000030 and made an generic C API he re-used the philosophy and
31 much code from libnjb. Many of the sample programs are for
32 example taken quite literally from libnjb. You find it here:
33 http://libnjb.sourceforge.net/
34
35
36Compiling programs for libmtp
37-----------------------------
38
39libmtp has support for the pkg-config script by adding a libmtp.pc
40entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
41"just" write:
42
43gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
44
45This also simplifies compilation using autoconf and pkg-config: just
46write e.g.
47
48PKG_CHECK_MODULES(MTP, libmtp)
49AC_SUBST(MTP_CFLAGS)
50AC_SUBST(MTP_LIBS)
51
52To have libmtp LIBS and CFLAGS defined. Needless to say, this will
53only work if you have pkgconfig installed on your system, but most
54people have nowadays.
55
56If your library is installed in e.g. /usr/local you may have to tell
57this to pkgconfig by setting the PKG_CONFIG_PATH thus:
58
59export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
60
61
62Documentation
63-------------
64
65Read the API documentation that can be generated with doxygen.
66It will be output in doc/html if you have Doxygen properly
67installed. (It will not be created unless you have Doxygen!)
68
69For information about the Media Transfer Protocol, see:
70http://en.wikipedia.org/wiki/Media_Transfer_Protocol
71
Linus Walleij7a83e552008-07-29 21:30:43 +000072The official 1.0 specification for MTP was released by the
73USB Implementers Forum in may, 2008. Prior to this, only a
74proprietary Microsoft version was available, and quite a few
75devices out there still use some aspects of the Microsoft
76version, which deviates from the specified standard. You can
77find the official specification here:
78http://www.usb.org/developers/devclass_docs/MTP_1.0.zip
Linus Walleij0dd71e92006-05-04 18:47:07 +000079
Linus Walleij1b91ca62008-10-17 07:07:56 +000080
81The Examples
82------------
83
84In the subdirectory "examples" you find a number of
85command-line tools, illustrating the use of libmtp in very
86simple terms.
87
88Please do not complain about the usability or documentation
89of these examples, they look like they do for two reasons:
90
911. They are examples, not tools. If they were intended for
92 day-to-day usage by commandline freaks, I would have
93 called them "tools" not "examples".
94
952. The MTP usage paradigm is that a daemon should hook
96 the device upon connection, and that it should be
97 released by unplugging. GUI tools utilizing HAL (hald)
98 and D-Bus do this much better than any commandline
99 program ever can. (See below on bugs.) Specificationwise
100 this is a bug, however it is present in many, many
101 devices.
102
103That said, if you want to pick up and maintain the examples,
104please volunteer.
105
106
Linus Walleij0dd71e92006-05-04 18:47:07 +0000107Contributing
108------------
109
110See the project page at http://libmtp.sourceforge.net/
Linus Walleijee73ef22006-08-27 19:56:00 +0000111We always need your help. There is a mailinglist and a
112bug report system there.
Linus Walleij6fd2f082006-03-28 07:19:22 +0000113
Linus Walleija1b66f22007-05-10 20:02:16 +0000114
115New Devices
116-----------
117
Linus Walleijfcf88912006-06-05 13:23:33 +0000118If you happen upon a device which libmtp claims it cannot
119autodetect, please submit the vendor ID and device ID
Linus Walleij9ee29402007-10-31 20:24:48 +0000120(these can be obtained from the "lsusb" and "lsusb -n"
121commands run as root) as a bug, patch or feature request
122on the Sourceforge bug tracker at our homepage. If it
123gives a sensible output from "mtp-detect" then please attach
124the result as well as it teach us some stuff about your
125device. If you've done some additional hacking, join our
126mailinglist and post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +0000127
Linus Walleija1b66f22007-05-10 20:02:16 +0000128If you want to be able to hack some more and you're not
129afraid of C hacking, add an entry for your device's
130vendor/product ID and a descriptive string to the database
Linus Walleij6dc01682007-11-15 21:23:46 +0000131in the file src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000132
133If you want to poke around to see if your device has some
134special pecularities, you can test some special device
Linus Walleij6dc01682007-11-15 21:23:46 +0000135flags (defined in src/device-flags.h) by inserting them
136together with your device entry in src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000137Flags can be tested in isolation or catenated with "|"
138(binary OR). If relatives to your device use a certain
139flag, chances are high that a new device will need it
140too, typically from the same manufacturer.
141
142The most common flag that needs to be set is the
143DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
144drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000145MTP access impossible. This is however not expected to
146really work: this is a problem being tracked as of
147now (2007-08-04). See the "last resort" solutions below
148if you really need to get your dual-mode device to work
149with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000150
Linus Walleijcc2cf972007-11-22 20:23:43 +0000151Another flag which is easy to identify is the
152DEVICE_FLAG_NO_ZERO_READS, which remedies connection
153timeouts when getting files, and some timeouts on e.g.
154successive "mtp-connect" calls.
155
Linus Walleij91fb0282007-09-03 21:16:08 +0000156If you are a device vendor, please consider assigning one
157of your employees as a contact person for libmtp, have them
158sign up to the libmtp development list and answer questions
159and post new device ID:s as they are released to our
160mailing list. By the way: do you have spare devices you
161can give us? Send them to Richard (Mac support) or Linus
162(Linux support). (So far nobody did that except for Microsoft
163who sent us a Zune by proxy!)
164
Linus Walleija1b66f22007-05-10 20:02:16 +0000165If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000166works under Windows, so we enjoy reading USB packet sniffs
167that reveal the low-level traffic carried out between
168Windows Media Player and your device. This can be done
Linus Walleij61c25682007-09-04 14:46:21 +0000169using e.g.:
170
171* USBsnoop:
172 http://benoit.papillault.free.fr/usbsnoop/
173
174* The trial version of HHD Softwares software-only
175 USB monitor. You need to get a copy of version 2.37 since
176 the newer trial versions won't let you carry out the
177 needed packet sniffs. (As of 2007-03-10 a copy can be found
178 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
179
Linus Walleijda558be2007-03-10 21:42:25 +0000180There are other USB monitors as well, some more expensive
181alternatives use hardware and even measure electronic
182characteristics of the traffic (which is far too much
183detail for us).
184
Linus Walleij91fb0282007-09-03 21:16:08 +0000185Device sniffs are an easy read since the PTP/MTP protocol
186is nicely structured. All commands will have a structure such
187as this in the log, we examplify with a object list request:
188
189PTP REQEUST:
190000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
191Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
192Send 0x20 bytes to the device:
193 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
194 Length TYPE CMD Trans# Param1
195
196 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
197 Param2 Param3 Param4 Param5
198
199[OPTIONAL] DATA PHASE:
200000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
201Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
202Get 0x1a bytes from the device:
203 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
204 Length TYPE CMD Trans# DATA
205
206 27 03 00 10 02 DC 04 00 00 30 '....Ü...0
207
208RESPONSE:
209000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
210Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
211Get 0xc bytes from the device:
212 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
213 Length TYPE CODE Trans#
214
215* One send (OUT to the device), two reads (IN from the device).
216
217* All three byte chunks commands are
218 sent/recieved/recieeved by the function ptp_transaction()
219 in the file ptp.c.
220
221* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
222 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
223 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
224 are ALWAYS called. The TYPE field correspond to this, so the
225 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
226 and "RESPONSE" (0x0003).
227
228* Notice that the byte order is little endian, so you need to read
229 each field from right to left.
230
231* This COMMAND has:
232 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
233 Transaction# 0x00000023.
234 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
235 0x00000000, in this case it means "get props for object 0x10000327",
236 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
237 parameters that are always zero (no idea what they mean or their
238 use).
239
240* The DATA has:
241 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
242 Transaction# 0x00000023.
243 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
244 Which means in this case, (and this is the tricky part) "here
245 you have 1 property", "for object 0x10000327", "it is property
246 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
247 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
248 is perfectly valid to have undefined object formats, since it
249 is a legal value defining this).
250
251* This RESPONSE has:
252 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
253 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
254 Transaction# 0x00000023.
Linus Walleijfcf88912006-06-05 13:23:33 +0000255
Linus Walleijd05fce62007-09-29 20:17:23 +0000256If you want to compare the Windows behaviour with a similar
Linus Walleij6dc01682007-11-15 21:23:46 +0000257operation using libmtp you can go into the src/libusb-glue.c
258file and uncomment the row that reads:
Linus Walleijd05fce62007-09-29 20:17:23 +0000259
260//#define ENABLE_USB_BULK_DEBUG
261
262(I.e. remove the two //.)
263
264This will make libmtp print out a hex dump of every bulk USB
265transaction. The bulk transactions contain all the PTP/MTP layer
266data, which is usually where the problems appear.
267
Linus Walleij6fd2f082006-03-28 07:19:22 +0000268
Linus Walleijbd7624c2007-05-28 10:48:54 +0000269Devices does not work - last resort:
270------------------------------------
271
272Some devices that are dual-mode are simply impossible to get
273to work under Linux because the usb-storage(.ko) kernel
274module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000275when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
276it DOES release it but the device will immediately be probed
277at the USB mass storage interface AGAIN because it
278enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000279
Linus Walleije20abaf2007-12-10 11:20:34 +0000280Linux: Try this, if you have a recent 2.6.x Linux kernel,
Linus Walleij584eb8d2007-09-05 19:51:27 +0000281run (as root) something like:
282
283> rmmod usb_storage ; mtp-detect
284
285You can run most any command or a client like gnomad2 or
286Amarok immediately after the rmmod command. This works
287sometimes. Another way:
Linus Walleijbd7624c2007-05-28 10:48:54 +0000288
Linus Walleij94f23d52007-08-04 19:37:28 +0000289* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000290
291* Add the line "blacklist usb-storage"
292
293* Reboot.
294
295Now none of you USB disks, flash memory sticks etc will be
296working (you just disabled them all). However you *can* try
297your device, and it might have started working because there
298is no longer a USB mass storage driver that tries to hook onto
299the mass storage interface of your device.
300
Linus Walleij94f23d52007-08-04 19:37:28 +0000301If not even blacklisting works (check with
302"lsmod | grep usb-storage"), there is some problem with
303something else and you may need to remove or rename the file
304/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
305manually.
306
Linus Walleijbd7624c2007-05-28 10:48:54 +0000307If you find the PerfectSolution(TM) to this dilemma, so you
308can properly switch for individual devices whether to use it
309as USB mass storage or not, please tell us how you did it. We
310know we cannot use udev, because udev is called after-the-fact:
311the device is already configured for USB mass storage when
312udev is called.
313
Linus Walleije20abaf2007-12-10 11:20:34 +0000314On Mac OS there is another ugly hack:
315
3161. Open up a terminal window
3172. Type:
318sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
319/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
320
321and when prompted enter your password.
322
3233. Restart.
324
325To reverse this change, just reverse the filenames:
326
327sudo mv /System/Library/Extensions/
328IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
329IOUSBMassStorageClass.kext
330
331and restart.
332
Linus Walleijbd7624c2007-05-28 10:48:54 +0000333
Linus Walleij15def332006-09-19 14:27:02 +0000334Calendar and contact support:
335-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000336
Linus Walleij3c16fe42006-04-30 07:53:41 +0000337The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000338and VCard (.vcf) files from programs like for example
339Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000340
Linus Walleij3c16fe42006-04-30 07:53:41 +0000341- The file must be in DOS (CR/LF) format, use the unix2dos
342 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000343
344- Repeat events in calendar files do not seem to be supported,
345 entries will only appear once.
346
347- Calendar (.ics) files should be stored in the folder "My Organizer"
348 when sent to the device (this directory should be autodetected
Linus Walleij80b2c722006-06-22 17:57:17 +0000349 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000350 -f "My Organizer" to sendfile for this) Apparently this file can
351 also contain tasklists.
352
353- Contact (.vcf) files should be stored in the folder "My Contacts"
354 when sent to the device. (-f "My Contacts")
355
356- Some devices are picky about the name of the calendar and
357 contact files. For example the Zen Microphoto wants:
358
Linus Walleijb1318d12006-09-25 14:59:26 +0000359 Calendar: My Organizer/6651416.ics
360 Contacts: My Organizer/6651416.vcf
361
362
363Syncing in with Evolution and Creative Devices
364----------------------------------------------
365
366Evolution can easily export .ics an .vcf files, but you currently
367need some command-line hacking to get you stuff copied over in
368one direction host -> device. The examples/ directory contains a script
369created for the Creative Zen Microphoto by Nicolas Tetreault.
370
Linus Walleij6e8cef42006-12-03 20:45:04 +0000371
372It's Not Our Bug!
373-----------------
374
375Some MTP devices have strange pecularities. We try to work around
376these whenever we can, sometimes we cannot work around it or we
377cannot test your solution.
378
Linus Walleij67038b92008-04-16 15:01:40 +0000379* Generic MTP/PTP disconnect misbehaviour: we have noticed that
380 Windows Media Player apparently never close the session to an MTP
381 device. There is a daemon in Windows that "hooks" the device
382 by opening a PTP session to any MTP device, whenever it is
383 plugged in. This daemon proxies any subsequent transactions
384 to/from the device and will never close the session, thus
385 Windows simply does not close sessions at all.
386
Linus Walleije2f65662008-12-07 20:44:11 +0000387 Typical sign of this illness: broken pipes on closing sessions,
388 on the main transfer pipes(s) or the interrupt pipe:
389
390 Closing session
391 usb_clear_halt() on INTERRUPT endpoint: Broken pipe
392 OK.
393
Linus Walleij67038b92008-04-16 15:01:40 +0000394 This means that device manufacturers doesn't notice any problems
395 with devices that do not correctly handle closing PTP/MTP
396 sessions, since Windows never do it. The proper way of closing
397 a session in Windows is to unplug the device, simply put.
398
399 Since libmtp actually tries to close sessions, some devices
400 may fail since the close session functionality has never been
401 properly tested, and "it works with Windows" is sort of the
402 testing criteria at some companies.
403
404 You can get Windows-like behaviour on Linux by running a HAL-aware
405 libmtp GUI client like Rhythmbox or Gnomad2, which will "hook"
406 the device when you plug it in, and "release" it if you unplug
407 it.
408
409 If this bug in your device annoys you, contact your device
410 manufacturer and ask them to test their product with some libmtp
411 program.
412
Linus Walleijb715ba62008-02-12 23:41:49 +0000413* Generic USB misbehaviour: some devices behave badly under MTP
414 and USB mass storage alike, even down to the lowest layers
415 of USB. You can always discuss such issues at the linux-usb
416 mailing list if you're using Linux:
417 http://www.linux-usb.org/mailing.html
418
Linus Walleij76b185d2008-02-12 23:46:14 +0000419 If you have a problem specific to USB mass storage mode, there
420 is a list of strange behaving devices in the Linux kernel:
421 http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h
Linus Walleijf7d8df12008-02-13 00:02:17 +0000422 You can discuss this too on the mentioned list, for understanding
423 the quirks, see:
424 http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt
Linus Walleij76b185d2008-02-12 23:46:14 +0000425
Linus Walleijdeddc342008-08-16 23:52:06 +0000426* Kernel bug on Linux. Linux 2.6.16 is generally speaking required
427 to use any MTP device under USB 2.0. This is because the EHCI
428 driver previously did not support zero-length writes to endpoints.
429 It should work in most cases however, or if you connect it
430 to an UHCI/OHCI port instead (yielding lower speed). But
431 please just use a recent kernel.
432
Linus Walleij07bb5382008-07-31 20:21:09 +0000433* Zen models AVI file seeking problem: the Zens cannot parse the
434 files for the runlength metadata. Do not transfer file with e.g.
435 mtp-sendfile, use mtp-sendtr and set the length of the track to
436 the apropriate number of seconds and it will work. In graphical
437 clients, use a "track transfer" function to send these AVI files,
438 the Zens need the metadata associated with tracks to play back
439 movies properly. Movies are considered "tracks" in the MTP world.
440
Linus Walleij64e2e982008-08-01 21:51:13 +0000441* Some devices that disregard the metadata sent with the MTP
442 commands will parse the files for e.g. ID3 metadata. Some still
443 of these devices expect only ID3v2.3 metadata and will fail with
444 a modern ID3v2,4 tag writer, like many of those found in Linux
445 applications. Windows Media Player use ID3v2.3 only, so many
446 manufacturers only test this version.
447
Linus Walleij6e8cef42006-12-03 20:45:04 +0000448* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
449 that makes it drop the last two characters off a playlist name.
450 It is fixed in later firmware.
451
Linus Walleijc41f2e82007-03-12 22:26:00 +0000452* For Creative Technology devices, there are hard limits on how
453 many files can be put onto the device. For a 30 GiB device (like
454 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
455 is 15000 files. For further Creative pecularities, see the
456 FAQ sections at www.nomadness.net.
457
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000458* Sandisk sansa c150 and probably several other Sandisk devices
459 (and possibly devices from other manufacturers) have a dual
460 mode with MTP and USB mass storage. The device will initially
461 claim to be mass storage so udev will capture is and make the
Linus Walleijda558be2007-03-10 21:42:25 +0000462 use of MTP mode impossible. One way of avoiding it could be to
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000463 be to blacklist the "usb-storage" module in
464 /etc/modprobe.c/blacklist with a row like this:
Linus Walleijda558be2007-03-10 21:42:25 +0000465 "blacklist usb-storage". Some have even removed the
466 "usb-storage.ko" (kernel module file) to avoid loading.
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000467
Linus Walleijda558be2007-03-10 21:42:25 +0000468* The iriver devices (possibly all of them) cannot handle the
Linus Walleij6e8cef42006-12-03 20:45:04 +0000469 enhanced GetObjectPropList MTP command (0x9805) properly. So
470 they have been banned from using it.
471
Linus Walleijda558be2007-03-10 21:42:25 +0000472* iriver devices have problems with older versions of libmtp and
Linus Walleij82265222007-03-04 19:47:08 +0000473 with new devices libmtp does not know of as of yet, since it
474 has an oldstyle USB device controller that cannot handle zero
Linus Walleijda558be2007-03-10 21:42:25 +0000475 writes. (Register your device with us!) All their devices are
476 likely to need a special device flag in the src/libusb-glue.c
477 database.
Linus Walleij82265222007-03-04 19:47:08 +0000478
Linus Walleij6e8cef42006-12-03 20:45:04 +0000479* The Samsung Yepp T9 has several strange characteristics, some
480 that we've managed to work around. (For example it will return
481 multiple PTP packages in a single transaction.)
482
Linus Walleijf2711b32007-02-26 20:18:40 +0000483* The early firmware for Philips HDD players is known to be
484 problematic. Please upgrade to as new firmware as you can get.
485 (Yes this requires some kind of Windows Installation I think.)
486
Linus Walleijb5a4f922008-05-11 20:15:00 +0000487* Philips HDD 1630/16 or 1630/17 etc may lock themselves up,
488 turning inresponsive due to internal corruption. This typically
489 gives an error in opening the PTP session. Apparently you can
490 do a "repair" with the firmware utility (Windows only) which
491 will often fix this problem and make the device responsive
492 again.
493
Linus Walleij9340aac2007-10-01 10:02:05 +0000494* Some devices that implement GetObjectPropList (0x9805) will
495 not return the entire object list if you request a list for object
496 0xffffffffu. (But they should.) So they may need the special
497 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
498
499* Some (smaller) subset of devices cannot even get all the
500 properties for a single object in one go, these need the
501 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
502 iriver devices seem to have this bug.
503
504* The Toshiba Gigabeat S (and probably its sibling the
505 Microsoft Zune and other Toshiba devices) will only display
506 album information tags for a song in case there is also
507 an abstract album (created with the album interface) with
508 the exact same name.
Linus Walleijd132d8e2007-04-03 23:24:54 +0000509
Linus Walleij265b9d62007-11-25 20:08:15 +0000510* The Zen Vision:M has an older firmware which is very corrupt,
511 it is incompatible with the Linux USB stack altogether. The
512 kernel dmesg will look something like this, and you have to
513 upgrade the firmware using Windows:
514 usb 4-5: new high speed USB device using ehci_hcd and address 5
515 usb 4-5: configuration #1 chosen from 1 choice
516 usb 4-5: can't set config #1, error -110
Linus Walleijd132d8e2007-04-03 23:24:54 +0000517
Linus Walleij103a78e2008-08-25 20:48:52 +0000518* The Sirus Stiletto does not seem to allow you to copy any files
519 off the device. This may be someone's idea of copy protection.
Linus Walleijb715ba62008-02-12 23:41:49 +0000520
Linus Walleij1b91ca62008-10-17 07:07:56 +0000521
Linus Walleijd132d8e2007-04-03 23:24:54 +0000522Lost symbols
523------------
524
525Shared libraries can be troublesome to users not experienced with
526them. The following is a condensed version of a generic question
527that has appeared on the libmtp mailing list from time to time.
528
529> PTP: Opening session
530> Queried Creative Zen Vision:M
531> gnomad2: relocation error: gnomad2: undefined symbol:
532> LIBMTP_Get_Storageinfo
533> (...)
534> Are these type of errors related to libmtp or something else?
535
536The problem is of a generic nature, and related to dynamic library
537loading. It is colloquially known as "dependency hell".
538(http://en.wikipedia.org/wiki/Dependency_hell)
539
540The gnomad2 application calls upon the dynamic linker in Linux to
541resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
542(ELF symbol, or link point or whatever you want to call them, a
543symbol is a label on a memory address that the linker shall
544resolve from label to actual address.)
545For generic information on this subject see the INSTALL file and
546this Wikipedia page:
547
548http://en.wikipedia.org/wiki/Library_(computing)
549
550When Linux /lib/ld-linux.so.X is called to link the symbols compiled
551into gnomad2 (or any other executable using libmtp), it examines the
552ELF file for the libmtp.so.X file it finds first and cannot resolve
553the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
554problem witj) from it, since it's probably not there. There are many
555possible causes of this symbol breakage:
556
5571) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
558 whatever) that do not match up. Typical cause: your gnomad2 package was
559 built against a newer version of libmtp than what's installed on your
560 machine. Another typical cause: you installed a package you found on
561 the web, somewhere, the dependency resolution system did not protest
562 properly (as it should) or you forced it to install anyway, ignoring
563 some warnings.
564
5652) You compiled libmtp and/or gnomad2 from source, installing both or
566 either in /usr/local/lib and /usr/local/bin. This means at compile-time
567 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
568 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
569 order to resolve the symbols. This loader will look into the file
570 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
571 paths to libraries to be used for resolving the symbols. If you have
572 some older version of libmtp in e.g. /usr/lib (typically installed by a
573 package manager) it will take precedence over the new version you just
574 installed in /usr/local/lib and the newly compiled library in
575 /usr/local/lib will *not* be used, resulting in this error message.
576
5773) You really did install the very latest versions (as of writing libmtp
578 0.1.5 and gnomad2 2.8.11) from source and there really is no
579 pre-installed package of either on your machine. In that case I'm
580 totally lost, I have no idea what's causing this.
581
582Typical remedies:
583
5841) If you don't want to mess around with your system and risk these
585 situations, only use pre-packaged software that came with the
586 distribution or its official support channels. If it still breaks,
587 blame your distribution, they're not packaging correctly. Relying on
588 properly packaged software and not installing things yourself *is* the
589 Linux solution to the "dependency hell" problem.
590
5912) Read about dynamically linked library handling until the stuff I wrote
592 about in the previous list sounds like music to your ears, inspect
593 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
594 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
595 YaST or whatever your distribution uses, compile libmtp and gnomad2
596 (or whatever) from source only and you will be enlighted.
597
598I don't know if this helps you, it's the best answer we can give.
Linus Walleij387e37a2008-10-29 17:22:22 +0000599
600
601API is obscure - I want plain files!
602------------------------------------
603
604PTP/MTP devices does not actually contain "files", they contain
605objects. These objects have file names, but that is actually
606just a name tag on the object.
607
608Folders/directories aren't really such entities: they are just
609objects too, albeit objects that can act as parent to other
610objects. They are called "association and are created in atomic
611fashion and even though there is an MTP command to get all the
612associations of an association, this command is optional so it is
613perfectly possible (and most common, actually) to create devices
614where the "folders" (which are actually associations) have no idea
615whatsoever of what files they are associated as parents to
616(i.e. which files they contain). This is very easy for device
617manufacturers to implement, all the association has to be done by
618the MTP Initiator / host computer.
619
620Moving a file to a new folder is for example very simple in a
621"real" file system. In PTP/MTP devices it is often not even possible,
622some devices *may* be able to do that. But actually the only
623reliable way of doing that is to upload the file to the host,
624download it with the new parent, then scratch the old file.
625We have played with the idea of implementing this time consuming
626function, perhaps we will.
627
628Playlists and albums aren't really files, thinking about
629them as files like the hacks in libgphoto2 is really backwards. They are
630called associations and are more like a symbolic link that links in a
631star-shaped pattern to all the files that are part of the album/playlist.
632Some devices (Samsung) thought that was too complicated and have a
633different way of storing playlists in an UTF-16 encoded .spl-like file
634instead! This is why playlists/albums must have their own structs and
635functions.
636
637
638I Want Streaming!
639-----------------
640
641Streaming reads is easy. Just connect the output file descriptor from
642LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)
643wherever you want.
644
645People have connected this to TCP sockets for streaming web servers
646etc, works like a charm. Some devices will even survive if the callback
647functions return non-zero and cancel the download. Some devices will
648lock up and even require a reset if you do that. Devices are poorly
649implemented so that's life. If you want to stream off a device, the
650best idea is always to stream the entire file and discard the stuff
651at the end you don't want. It will incur a delay if you e.g. want to
652skip between tracks, sadly.
653
654Then we get to the complicated things: streaming WRITES...
655
656There is a function:
657LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks)
658which will write a file to a device from a file descriptor, which may
659be a socket or whatever.
660
661HOWEVER: this requires a piece of metadata with the .filesize properly
662set first.
663
664This is not because we think it is funny to require that, the protocol
665requires it. The reason is that PTP/MTP is a transactional file system
666and it wants to be able to deny file transfer if the file won't fit on
667the device, so the transaction never even starts, it's impossible to
668start a transaction without giving file length.
669
670People really want streaming so I tried a lot of hacks to see if they
671would work, such as setting file size to 0xffffffffU or something other
672unnaturally big and then aborting the file transfer when the stream ends.
673It doesn't work: either the device crashes or the file simply disappears
674since the device rolls back all failed transactions.
675
676So this is an inherent limitation of the PTP/MTP protocol.