Home | History | Annotate | only in /external/libmtp
Up to higher level directory
NameDateSize
aclocal.m413-Nov-201279.3K
AUTHORS13-Nov-20121.4K
ChangeLog13-Nov-201290K
config.guess13-Nov-201243.8K
config.h13-Nov-20125.5K
config.h.in13-Nov-20125.2K
config.rpath13-Nov-20120
config.sub13-Nov-201232.6K
configure13-Nov-2012519.7K
configure.ac13-Nov-20123.5K
COPYING13-Nov-201225.8K
depcomp13-Nov-201218.2K
doc/13-Nov-2012
examples/13-Nov-2012
hotplug.sh.in13-Nov-20124.9K
INSTALL13-Nov-20127.3K
install-sh13-Nov-201213.3K
libmtp.pc13-Nov-2012333
libmtp.pc.in13-Nov-2012333
libmtp.sh13-Nov-20121.2K
libmtp.sh.in13-Nov-20121.2K
libmtp.xcodeproj/13-Nov-2012
ltmain.sh13-Nov-2012237.5K
m4/13-Nov-2012
MacConfigExternalDebug.xcconfig13-Nov-2012615
MacConfigExternalRelease.xcconfig13-Nov-2012854
Makefile.am13-Nov-2012466
Makefile.in13-Nov-201225K
missing13-Nov-201211.2K
README13-Nov-201228.7K
README.windows.txt13-Nov-20122.8K
src/13-Nov-2012
TODO13-Nov-20124.9K

README

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

README.windows.txt

      1 This file was created by James Ravenscroft <ravenscroftj (a] gmail.com> as a direct revision of Farooq Zaman's work with LibMTP on Windows.
      2 
      3  CHANGELOG
      4 ----------------
      5 14th January 2009: Created the first revision of this file taking information from the work of Farooq Zaman.
      6 
      7  1.0 Compilation of LibMTP on Windows 2000/XP/NT 
      8 -----------------------------------------------------------
      9 LibMTP currently compiles under Windows using MingW/MSys. The source relies upon the __WIN32__ macro which is defined by MinGW by default.
     10 
     11 Libraries:
     12 LibMTP currently depends on LibUSB and libiconv. There are currently projects that port both of these libraries to Windows. Binary files can be
     13 obtained from:
     14 
     15 LibUSB Win32 - http://libusb-win32.sourceforge.net/
     16 
     17 LibIconv - http://gnuwin32.sourceforge.net/packages/libiconv.htm
     18 
     19 With both of these libraries extracted and placed in MinGW's search path, you can compile the library by opening the Msys prompt, navigating to
     20 the path where the extracted LibMTP source files can be found and typing:
     21 
     22 ./configure
     23 make all
     24 make install
     25 
     26 
     27 
     28  2.0 LibUSB and Driver Issues for Windows
     29 ----------------------------------------------
     30 
     31 Unfortunately, Windows does not have abstract USB support and depends upon specific drivers for each and every device you use. Fortunately, 
     32 LibUSB-Win32 provide a solution to this problem. LibMTP takes advantage of the LibUSB-Win32 Device Driver package.
     33 
     34 1. Download the latest device driver binary package (libusb-win32-device-bin-x.x.x.x.tar.gz) from http://sourceforge.net/project/showfiles.php?group_id=78138
     35 2. Upon extraction, plug in your music device and run bin/inf-wizard.exe. Selecting your device and saving the inf file in the project root directory.
     36 3. Copy the files "bin/libusb0.dll" and "libusb0.sys" or "libusb0_x64.dll" and "libusb0_x64.sys" for 32-bit or 64-bit operating systems respectively.
     37 4. Goto Start -> Run, type "devmgmt.msc" and press "ok".
     38 5. Select your music device from the list and click Action -> Update Driver, Choose "No, not this time" if prompted to connect to microsoft.
     39 6. Choose "Install from a list or specific location".
     40 7.  Choose "Don't search, I will choose the driver to install
     41 8. Click the "Have Disk..." button in the bottom right corner of the prompt
     42 9. Browse to your .inf file and select it. Press Ok 
     43 10. The name of your music device should appear in the prompt, click it and click "Next>" (Ignore any prompts about Driver Signing, continuing 
     44 installation of the selected driver).
     45 11. Click finish to end the driver install process.
     46 
     47 To get your old driver back:
     48 
     49 1. Goto Start -> Run, type "devmgmt.msc" and press "ok".
     50 2. Select your music device, right click on it and click "Properties"
     51 3. Go to the "Driver" pane and select "Roll Back Driver".
     52 
     53  3.0 
     54 ----------------------------------------------
     55