README - platform/external/libmtp - Gitiles

 Building and Installing
 -----------------------

 See the "INSTALL" file.


 Heritage
 --------

 libmtp is based on several ancestors:

 * libptp2 by Mariusz Woloszyn was the starting point used
   by Richard A. Low for the initial starter port. You can
   find it at http://libptp.sourceforge.net/

 * libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
   used at a later stage since it was (is) more actively
   maintained. libmtp tracks the PTP implementation in
   libgphoto2 and considers it an upstream project. We will
   try to submit anything generally useful back to libgphoto2
   and not make double efforts. In practice this means we
   use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
   source code. If you need to change things in these files,
   make sure it is so general that libgphoto2 will want to
   merge it to their codebase too. You find libgphoto2 as part
   of gPhoto: http://gphoto.sourceforge.net/

 * libnjb was a project that Richard and Linus were working
   on before libmtp. When Linus took Richards initial port
   and made an generic C API he re-used the philosophy and
   much code from libnjb. Many of the sample programs are for
   example taken quite literally from libnjb. You find it here:
   http://libnjb.sourceforge.net/


 Compiling programs for libmtp
 -----------------------------

 libmtp has support for the pkg-config script by adding a libmtp.pc
 entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
 "just" write:

 gcc -o foo `pkg-config --cflags --libs libmtp` foo.c

 This also simplifies compilation using autoconf and pkg-config: just
 write e.g.

 PKG_CHECK_MODULES(MTP, libmtp)
 AC_SUBST(MTP_CFLAGS)
 AC_SUBST(MTP_LIBS)

 To have libmtp LIBS and CFLAGS defined. Needless to say, this will
 only work if you have pkgconfig installed on your system, but most
 people have nowadays.

 If your library is installed in e.g. /usr/local you may have to tell
 this to pkgconfig by setting the PKG_CONFIG_PATH thus:

 export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig


 Documentation
 -------------

 Read the API documentation that can be generated with doxygen.
 It will be output in doc/html if you have Doxygen properly
 installed. (It will not be created unless you have Doxygen!)

 For information about the Media Transfer Protocol, see:
 http://en.wikipedia.org/wiki/Media_Transfer_Protocol


 Contributing
 ------------

 See the project page at http://libmtp.sourceforge.net/
 We always need your help. There is a mailinglist and a
 bug report system there.


 New Devices
 -----------

 If you happen upon a device which libmtp claims it cannot
 autodetect, please submit the vendor ID and device ID
 (these can be obtained from the "lsusb" and "lsusb -n"
 commands run as root) as a bug, patch or feature request
 on the Sourceforge bug tracker at our homepage. If it
 gives a sensible  output from "mtp-detect" then please attach
 the result as well as it teach us some stuff about your
 device. If you've done some additional hacking, join our
 mailinglist and post your experiences there.

 If you want to be able to hack some more and you're not
 afraid of C hacking, add an entry for your device's
 vendor/product ID and a descriptive string to the database
 in the file src/music-players.h.

 If you want to poke around to see if your device has some
 special pecularities, you can test some special device
 flags (defined in src/device-flags.h) by inserting them
 together with your device entry in src/music-players.h.
 Flags can be tested in isolation or catenated with "|"
 (binary OR). If relatives to your device use a certain
 flag, chances are high that a new device will need it
 too, typically from the same manufacturer.

 The most common flag that needs to be set is the
 DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
 drivers that may have attached to the device making
 MTP access impossible. This is however not expected to
 really work: this is a problem being tracked as of
 now (2007-08-04). See the "last resort" solutions below
 if you really need to get your dual-mode device to work
 with MTP.

 Another flag which is easy to identify is the
 DEVICE_FLAG_NO_ZERO_READS, which remedies connection
 timeouts when getting files, and some timeouts on e.g.
 successive "mtp-connect" calls.

 If you are a device vendor, please consider assigning one
 of your employees as a contact person for libmtp, have them
 sign up to the libmtp development list and answer questions
 and post new device ID:s as they are released to our
 mailing list. By the way: do you have spare devices you
 can give us? Send them to Richard (Mac support) or Linus
 (Linux support). (So far nobody did that except for Microsoft
 who sent us a Zune by proxy!)

 If your device is very problematic we are curious of how it
 works under Windows, so we enjoy reading USB packet sniffs
 that reveal the low-level traffic carried out between
 Windows Media Player and your device. This can be done
 using e.g.:

 * USBsnoop:
   http://benoit.papillault.free.fr/usbsnoop/

 * The trial version of HHD Softwares software-only
   USB monitor. You need to get a copy of version 2.37 since
   the newer trial versions won't let you carry out the
   needed packet sniffs. (As of 2007-03-10 a copy can be found
   at: http://www.cobbleware.com/files/usb-monitor-237.exe)

 There are other USB monitors as well, some more expensive
 alternatives use hardware and even measure electronic
 characteristics of the traffic (which is far too much
 detail for us).

 Device sniffs are an easy read since the PTP/MTP protocol
 is nicely structured. All commands will have a structure such
 as this in the log, we examplify with a object list request:

 PTP REQEUST:
 000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
 Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
 Send 0x20 bytes to the device:
  20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10    ......?#...'...
  Length      TYPE  CMD   Trans#      Param1

  00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00   .....Ü..........
  Param2      Param3      Param4      Param5

 [OPTIONAL] DATA PHASE:
 000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
 Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
 Get 0x1a bytes from the device:
  1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00   .......?#.......
  Length      TYPE  CMD   Trans#      DATA

  27 03 00 10 02 DC 04 00 00 30                     '....Ü...0

 RESPONSE:
 000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
 Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
 Get 0xc bytes from the device:
  0C 00 00 00 03 00 01 20 23 00 00 00               ....... #...
  Length      TYPE  CODE  Trans#

 * One send (OUT to the device), two reads (IN from the device).

 * All three byte chunks commands are
   sent/recieved/recieeved by the function  ptp_transaction()
   in the file ptp.c.

 * It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
   or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
   libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
   are ALWAYS called. The TYPE field correspond to this, so the
   TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
   and "RESPONSE" (0x0003).

 * Notice that the byte order is little endian, so you need to read
   each field from right to left.

 * This COMMAND has:
   CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
   Transaction# 0x00000023.
   REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
     0x00000000, in this case it means "get props for object 0x10000327",
     "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
     parameters that are always zero (no idea what they mean or their
     use).

 * The DATA has:
   CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
   Transaction# 0x00000023.
   Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
   Which means in this case, (and this is the tricky part) "here
   you have 1 property", "for object 0x10000327", "it is property
   0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
   (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
   is perfectly valid to have undefined object formats, since it
   is a legal value defining this).

 * This RESPONSE has:
   CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
   Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
   Transaction# 0x00000023.

 If you want to compare the Windows behaviour with a similar
 operation using libmtp you can go into the src/libusb-glue.c
 file and uncomment the row that reads:

 //#define ENABLE_USB_BULK_DEBUG

 (I.e. remove the two //.)

 This will make libmtp print out a hex dump of every bulk USB
 transaction. The bulk transactions contain all the PTP/MTP layer
 data, which is usually where the problems appear.


 Devices does not work - last resort:
 ------------------------------------

 Some devices that are dual-mode are simply impossible to get
 to work under Linux because the usb-storage(.ko) kernel
 module hook them first, and refuse to release them, even
 when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
 it DOES release it but the device will immediately be probed
 at the USB mass storage interface AGAIN because it
 enumerates.)

 Linux: Try this, if you have a recent 2.6.x Linux kernel,
 run (as root) something like:

 > rmmod usb_storage ; mtp-detect

 You can run most any command or a client like gnomad2 or
 Amarok immediately after the rmmod command. This works
 sometimes. Another way:

 * Edit /etc/modprobe.d/blacklist

 * Add the line "blacklist usb-storage"

 * Reboot.

 Now none of you USB disks, flash memory sticks etc will be
 working (you just disabled them all). However you *can* try
 your device, and it might have started working because there
 is no longer a USB mass storage driver that tries to hook onto
 the mass storage interface of your device.

 If not even blacklisting works (check with
 "lsmod | grep usb-storage"), there is some problem with
 something else and you may need to remove or rename the file
 /lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
 manually.

 If you find the PerfectSolution(TM) to this dilemma, so you
 can properly switch for individual devices whether to use it
 as USB mass storage or not, please tell us how you did it. We
 know we cannot use udev, because udev is called after-the-fact:
 the device is already configured for USB mass storage when
 udev is called.

 On Mac OS there is another ugly hack:

 1. Open up a terminal window
 2. Type:
 sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
 /System/Library/Extensions/IOUSBMassStorageClass.kext.disabled

 and when prompted enter your password.

 3. Restart.

 To reverse this change, just reverse the filenames:

 sudo mv /System/Library/Extensions/
 IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
 IOUSBMassStorageClass.kext

 and restart.


 Calendar and contact support:
 -----------------------------

 The Creative Zen series can read VCALENDAR2 (.ics) files
 and VCard (.vcf) files from programs like for example
 Evolution with the following limitations/conditions:

 - The file must be in DOS (CR/LF) format, use the unix2dos
   program to convert if needed

 - Repeat events in calendar files do not seem to be supported,
   entries will only appear once.

 - Calendar (.ics) files should be stored in the folder "My Organizer"
   when sent to the device (this directory should be autodetected
   for use with calendar files, otherwise use the option
   -f "My Organizer" to sendfile for this) Apparently this file can
   also contain tasklists.

 - Contact (.vcf) files should be stored in the folder "My Contacts"
   when sent to the device. (-f "My Contacts")

 - Some devices are picky about the name of the calendar and
   contact files. For example the Zen Microphoto wants:

   Calendar: My Organizer/6651416.ics
   Contacts: My Organizer/6651416.vcf


 Syncing in with Evolution and Creative Devices
 ----------------------------------------------

 Evolution can easily export .ics an .vcf files, but you currently
 need some command-line hacking to get you stuff copied over in
 one direction host -> device. The examples/ directory contains a script
 created for the Creative Zen Microphoto by Nicolas Tetreault.


 It's Not Our Bug!
 -----------------

 Some MTP devices have strange pecularities. We try to work around
 these whenever we can, sometimes we cannot work around it or we
 cannot test your solution.

 * The Zen Vision:M (possibly more Creative Zens) has a firmware bug
   that makes it drop the last two characters off a playlist name.
   It is fixed in later firmware.

 * For Creative Technology devices, there are hard limits on how
   many files can be put onto the device. For a 30 GiB device (like
   the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
   is 15000 files. For further Creative pecularities, see the
   FAQ sections at www.nomadness.net.

 * Sandisk sansa c150 and probably several other Sandisk devices
   (and possibly devices from other manufacturers) have a dual
   mode with MTP and USB mass storage. The device will initially
   claim to be mass storage so udev will capture is and make the
   use of MTP mode impossible. One way of avoiding it could be to
   be to blacklist the "usb-storage" module in
   /etc/modprobe.c/blacklist with a row like this:
   "blacklist usb-storage". Some have even removed the
   "usb-storage.ko" (kernel module file) to avoid loading.

 * The iriver devices (possibly all of them) cannot handle the
   enhanced GetObjectPropList MTP command (0x9805) properly. So
   they have been banned from using it.

 * iriver devices have problems with older versions of libmtp and
   with new devices libmtp does not know of as of yet, since it
   has an oldstyle USB device controller that cannot handle zero
   writes. (Register your device with us!) All their devices are
   likely to need a special device flag in the src/libusb-glue.c
   database.

 * The Samsung Yepp T9 has several strange characteristics, some
   that we've managed to work around. (For example it will return
   multiple PTP packages in a single transaction.)

 * The early firmware for Philips HDD players is known to be
   problematic. Please upgrade to as new firmware as you can get.
   (Yes this requires some kind of Windows Installation I think.)

 * Some devices that implement GetObjectPropList (0x9805) will
   not return the entire object list if you request a list for object
   0xffffffffu. (But they should.) So they may need the special
   DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.

 * Some (smaller) subset of devices cannot even get all the
   properties for a single object in one go, these need the
   DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
   iriver devices seem to have this bug.

 * The Toshiba Gigabeat S (and probably its sibling the
   Microsoft Zune and other Toshiba devices) will only display
   album information tags for a song in case there is also
   an abstract album (created with the album interface) with
   the exact same name.

 * The Zen Vision:M has an older firmware which is very corrupt,
   it is incompatible with the Linux USB stack altogether. The
   kernel dmesg will look something like this, and you have to
   upgrade the firmware using Windows:
   usb 4-5: new high speed USB device using ehci_hcd and address 5
   usb 4-5: configuration #1 chosen from 1 choice
   usb 4-5: can't set config #1, error -110

 Lost symbols
 ------------

 Shared libraries can be troublesome to users not experienced with
 them. The following is a condensed version of a generic question
 that has appeared on the libmtp mailing list from time to time.

 > PTP: Opening session
 > Queried Creative Zen Vision:M
 > gnomad2: relocation error: gnomad2: undefined symbol:
 > LIBMTP_Get_Storageinfo
 > (...)
 > Are these type of errors related to libmtp or something else?

 The problem is of a generic nature, and related to dynamic library
 loading. It is colloquially known as "dependency hell".
 (http://en.wikipedia.org/wiki/Dependency_hell)

 The gnomad2 application calls upon the dynamic linker in Linux to
 resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
 (ELF symbol, or link point or whatever you want to call them, a
 symbol is a label on a memory address that the linker shall
 resolve from label to actual address.)
 For generic information on this subject see the INSTALL file and
 this Wikipedia page:

 http://en.wikipedia.org/wiki/Library_(computing)

 When Linux /lib/ld-linux.so.X is called to link the symbols compiled
 into gnomad2 (or any other executable using libmtp), it examines the
 ELF file for the libmtp.so.X file it finds first and cannot resolve
 the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
 problem witj) from it, since it's probably not there. There are many
 possible causes of this symbol breakage:

 1) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
     whatever) that do not match up. Typical cause: your gnomad2 package was
     built against a newer version of libmtp than what's installed on your
     machine. Another typical cause: you installed a package you found on
     the web, somewhere, the dependency resolution system did not protest
     properly (as it should) or you forced it to install anyway, ignoring
     some warnings.

 2) You compiled libmtp and/or gnomad2 from source, installing both or
     either in /usr/local/lib and /usr/local/bin. This means at compile-time
     gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
     depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
     order to resolve the symbols. This loader will look into the file
     /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
     paths to libraries to be used for resolving the symbols. If you have
     some older version of libmtp in e.g. /usr/lib (typically installed by a
     package manager) it will take precedence over the new version you just
     installed in /usr/local/lib and the newly compiled library in
     /usr/local/lib will *not* be used, resulting in this error message.

 3) You really did install the very latest versions (as of writing libmtp
     0.1.5 and gnomad2 2.8.11) from source and there really is no
     pre-installed package of either on your machine. In that case I'm
     totally lost, I have no idea what's causing this.

 Typical remedies:

 1) If you don't want to mess around with your system and risk these
     situations, only use pre-packaged software that came with the
     distribution or its official support channels. If it still breaks,
     blame your distribution, they're not packaging correctly. Relying on
     properly packaged software and not installing things yourself *is* the
     Linux solution to the "dependency hell" problem.

 2) Read about dynamically linked library handling until the stuff I wrote
     about in the previous list sounds like music to your ears, inspect
     your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
     /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
     YaST or whatever your distribution uses, compile libmtp and gnomad2
     (or whatever) from source only and you will be enlighted.

 I don't know if this helps you, it's the best answer we can give.
	Building and Installing
	-----------------------

	See the "INSTALL" file.


	Heritage
	--------

	libmtp is based on several ancestors:

	* libptp2 by Mariusz Woloszyn was the starting point used
	by Richard A. Low for the initial starter port. You can
	find it at http://libptp.sourceforge.net/

	* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
	used at a later stage since it was (is) more actively
	maintained. libmtp tracks the PTP implementation in
	libgphoto2 and considers it an upstream project. We will
	try to submit anything generally useful back to libgphoto2
	and not make double efforts. In practice this means we
	use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
	source code. If you need to change things in these files,
	make sure it is so general that libgphoto2 will want to
	merge it to their codebase too. You find libgphoto2 as part
	of gPhoto: http://gphoto.sourceforge.net/

	* libnjb was a project that Richard and Linus were working
	on before libmtp. When Linus took Richards initial port
	and made an generic C API he re-used the philosophy and
	much code from libnjb. Many of the sample programs are for
	example taken quite literally from libnjb. You find it here:
	http://libnjb.sourceforge.net/


	Compiling programs for libmtp
	-----------------------------

	libmtp has support for the pkg-config script by adding a libmtp.pc
	entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
	"just" write:

	gcc -o foo `pkg-config --cflags --libs libmtp` foo.c

	This also simplifies compilation using autoconf and pkg-config: just
	write e.g.

	PKG_CHECK_MODULES(MTP, libmtp)
	AC_SUBST(MTP_CFLAGS)
	AC_SUBST(MTP_LIBS)

	To have libmtp LIBS and CFLAGS defined. Needless to say, this will
	only work if you have pkgconfig installed on your system, but most
	people have nowadays.

	If your library is installed in e.g. /usr/local you may have to tell
	this to pkgconfig by setting the PKG_CONFIG_PATH thus:

	export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig


	Documentation
	-------------

	Read the API documentation that can be generated with doxygen.
	It will be output in doc/html if you have Doxygen properly
	installed. (It will not be created unless you have Doxygen!)

	For information about the Media Transfer Protocol, see:
	http://en.wikipedia.org/wiki/Media_Transfer_Protocol


	Contributing
	------------

	See the project page at http://libmtp.sourceforge.net/
	We always need your help. There is a mailinglist and a
	bug report system there.


	New Devices
	-----------

	If you happen upon a device which libmtp claims it cannot
	autodetect, please submit the vendor ID and device ID
	(these can be obtained from the "lsusb" and "lsusb -n"
	commands run as root) as a bug, patch or feature request
	on the Sourceforge bug tracker at our homepage. If it
	gives a sensible output from "mtp-detect" then please attach
	the result as well as it teach us some stuff about your
	device. If you've done some additional hacking, join our
	mailinglist and post your experiences there.

	If you want to be able to hack some more and you're not
	afraid of C hacking, add an entry for your device's
	vendor/product ID and a descriptive string to the database
	in the file src/music-players.h.

	If you want to poke around to see if your device has some
	special pecularities, you can test some special device
	flags (defined in src/device-flags.h) by inserting them
	together with your device entry in src/music-players.h.
	Flags can be tested in isolation or catenated with "\|"
	(binary OR). If relatives to your device use a certain
	flag, chances are high that a new device will need it
	too, typically from the same manufacturer.

	The most common flag that needs to be set is the
	DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
	drivers that may have attached to the device making
	MTP access impossible. This is however not expected to
	really work: this is a problem being tracked as of
	now (2007-08-04). See the "last resort" solutions below
	if you really need to get your dual-mode device to work
	with MTP.

	Another flag which is easy to identify is the
	DEVICE_FLAG_NO_ZERO_READS, which remedies connection
	timeouts when getting files, and some timeouts on e.g.
	successive "mtp-connect" calls.

	If you are a device vendor, please consider assigning one
	of your employees as a contact person for libmtp, have them
	sign up to the libmtp development list and answer questions
	and post new device ID:s as they are released to our
	mailing list. By the way: do you have spare devices you
	can give us? Send them to Richard (Mac support) or Linus
	(Linux support). (So far nobody did that except for Microsoft
	who sent us a Zune by proxy!)

	If your device is very problematic we are curious of how it
	works under Windows, so we enjoy reading USB packet sniffs
	that reveal the low-level traffic carried out between
	Windows Media Player and your device. This can be done
	using e.g.:

	* USBsnoop:
	http://benoit.papillault.free.fr/usbsnoop/

	* The trial version of HHD Softwares software-only
	USB monitor. You need to get a copy of version 2.37 since
	the newer trial versions won't let you carry out the
	needed packet sniffs. (As of 2007-03-10 a copy can be found
	at: http://www.cobbleware.com/files/usb-monitor-237.exe)

	There are other USB monitors as well, some more expensive
	alternatives use hardware and even measure electronic
	characteristics of the traffic (which is far too much
	detail for us).

	Device sniffs are an easy read since the PTP/MTP protocol
	is nicely structured. All commands will have a structure such
	as this in the log, we examplify with a object list request:

	PTP REQEUST:
	000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
	Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
	Send 0x20 bytes to the device:
	20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
	Length TYPE CMD Trans# Param1

	00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
	Param2 Param3 Param4 Param5

	[OPTIONAL] DATA PHASE:
	000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
	Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
	Get 0x1a bytes from the device:
	1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
	Length TYPE CMD Trans# DATA

	27 03 00 10 02 DC 04 00 00 30 '....Ü...0

	RESPONSE:
	000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
	Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
	Get 0xc bytes from the device:
	0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
	Length TYPE CODE Trans#

	* One send (OUT to the device), two reads (IN from the device).

	* All three byte chunks commands are
	sent/recieved/recieeved by the function ptp_transaction()
	in the file ptp.c.

	* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
	or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
	libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
	are ALWAYS called. The TYPE field correspond to this, so the
	TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
	and "RESPONSE" (0x0003).

	* Notice that the byte order is little endian, so you need to read
	each field from right to left.

	* This COMMAND has:
	CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
	Transaction# 0x00000023.
	REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
	0x00000000, in this case it means "get props for object 0x10000327",
	"any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
	parameters that are always zero (no idea what they mean or their
	use).

	* The DATA has:
	CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
	Transaction# 0x00000023.
	Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
	Which means in this case, (and this is the tricky part) "here
	you have 1 property", "for object 0x10000327", "it is property
	0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
	(PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
	is perfectly valid to have undefined object formats, since it
	is a legal value defining this).

	* This RESPONSE has:
	CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
	Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
	Transaction# 0x00000023.

	If you want to compare the Windows behaviour with a similar
	operation using libmtp you can go into the src/libusb-glue.c
	file and uncomment the row that reads:

	//#define ENABLE_USB_BULK_DEBUG

	(I.e. remove the two //.)

	This will make libmtp print out a hex dump of every bulk USB
	transaction. The bulk transactions contain all the PTP/MTP layer
	data, which is usually where the problems appear.


	Devices does not work - last resort:
	------------------------------------

	Some devices that are dual-mode are simply impossible to get
	to work under Linux because the usb-storage(.ko) kernel
	module hook them first, and refuse to release them, even
	when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
	it DOES release it but the device will immediately be probed
	at the USB mass storage interface AGAIN because it
	enumerates.)

	Linux: Try this, if you have a recent 2.6.x Linux kernel,
	run (as root) something like:

	> rmmod usb_storage ; mtp-detect

	You can run most any command or a client like gnomad2 or
	Amarok immediately after the rmmod command. This works
	sometimes. Another way:

	* Edit /etc/modprobe.d/blacklist

	* Add the line "blacklist usb-storage"

	* Reboot.

	Now none of you USB disks, flash memory sticks etc will be
	working (you just disabled them all). However you can try
	your device, and it might have started working because there
	is no longer a USB mass storage driver that tries to hook onto
	the mass storage interface of your device.

	If not even blacklisting works (check with
	"lsmod \| grep usb-storage"), there is some problem with
	something else and you may need to remove or rename the file
	/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
	manually.

	If you find the PerfectSolution(TM) to this dilemma, so you
	can properly switch for individual devices whether to use it
	as USB mass storage or not, please tell us how you did it. We
	know we cannot use udev, because udev is called after-the-fact:
	the device is already configured for USB mass storage when
	udev is called.

	On Mac OS there is another ugly hack:

	1. Open up a terminal window
	2. Type:
	sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
	/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled

	and when prompted enter your password.

	3. Restart.

	To reverse this change, just reverse the filenames:

	sudo mv /System/Library/Extensions/
	IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
	IOUSBMassStorageClass.kext

	and restart.


	Calendar and contact support:
	-----------------------------

	The Creative Zen series can read VCALENDAR2 (.ics) files
	and VCard (.vcf) files from programs like for example
	Evolution with the following limitations/conditions:

	- The file must be in DOS (CR/LF) format, use the unix2dos
	program to convert if needed

	- Repeat events in calendar files do not seem to be supported,
	entries will only appear once.

	- Calendar (.ics) files should be stored in the folder "My Organizer"
	when sent to the device (this directory should be autodetected
	for use with calendar files, otherwise use the option
	-f "My Organizer" to sendfile for this) Apparently this file can
	also contain tasklists.

	- Contact (.vcf) files should be stored in the folder "My Contacts"
	when sent to the device. (-f "My Contacts")

	- Some devices are picky about the name of the calendar and
	contact files. For example the Zen Microphoto wants:

	Calendar: My Organizer/6651416.ics
	Contacts: My Organizer/6651416.vcf


	Syncing in with Evolution and Creative Devices
	----------------------------------------------

	Evolution can easily export .ics an .vcf files, but you currently
	need some command-line hacking to get you stuff copied over in
	one direction host -> device. The examples/ directory contains a script
	created for the Creative Zen Microphoto by Nicolas Tetreault.


	It's Not Our Bug!
	-----------------

	Some MTP devices have strange pecularities. We try to work around
	these whenever we can, sometimes we cannot work around it or we
	cannot test your solution.

	* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
	that makes it drop the last two characters off a playlist name.
	It is fixed in later firmware.

	* For Creative Technology devices, there are hard limits on how
	many files can be put onto the device. For a 30 GiB device (like
	the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
	is 15000 files. For further Creative pecularities, see the
	FAQ sections at www.nomadness.net.

	* Sandisk sansa c150 and probably several other Sandisk devices
	(and possibly devices from other manufacturers) have a dual
	mode with MTP and USB mass storage. The device will initially
	claim to be mass storage so udev will capture is and make the
	use of MTP mode impossible. One way of avoiding it could be to
	be to blacklist the "usb-storage" module in
	/etc/modprobe.c/blacklist with a row like this:
	"blacklist usb-storage". Some have even removed the
	"usb-storage.ko" (kernel module file) to avoid loading.

	* The iriver devices (possibly all of them) cannot handle the
	enhanced GetObjectPropList MTP command (0x9805) properly. So
	they have been banned from using it.

	* iriver devices have problems with older versions of libmtp and
	with new devices libmtp does not know of as of yet, since it
	has an oldstyle USB device controller that cannot handle zero
	writes. (Register your device with us!) All their devices are
	likely to need a special device flag in the src/libusb-glue.c
	database.

	* The Samsung Yepp T9 has several strange characteristics, some
	that we've managed to work around. (For example it will return
	multiple PTP packages in a single transaction.)

	* The early firmware for Philips HDD players is known to be
	problematic. Please upgrade to as new firmware as you can get.
	(Yes this requires some kind of Windows Installation I think.)

	* Some devices that implement GetObjectPropList (0x9805) will
	not return the entire object list if you request a list for object
	0xffffffffu. (But they should.) So they may need the special
	DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.

	* Some (smaller) subset of devices cannot even get all the
	properties for a single object in one go, these need the
	DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
	iriver devices seem to have this bug.

	* The Toshiba Gigabeat S (and probably its sibling the
	Microsoft Zune and other Toshiba devices) will only display
	album information tags for a song in case there is also
	an abstract album (created with the album interface) with
	the exact same name.

	* The Zen Vision:M has an older firmware which is very corrupt,
	it is incompatible with the Linux USB stack altogether. The
	kernel dmesg will look something like this, and you have to
	upgrade the firmware using Windows:
	usb 4-5: new high speed USB device using ehci_hcd and address 5
	usb 4-5: configuration #1 chosen from 1 choice
	usb 4-5: can't set config #1, error -110

	Lost symbols
	------------

	Shared libraries can be troublesome to users not experienced with
	them. The following is a condensed version of a generic question
	that has appeared on the libmtp mailing list from time to time.

	> PTP: Opening session
	> Queried Creative Zen Vision:M
	> gnomad2: relocation error: gnomad2: undefined symbol:
	> LIBMTP_Get_Storageinfo
	> (...)
	> Are these type of errors related to libmtp or something else?

	The problem is of a generic nature, and related to dynamic library
	loading. It is colloquially known as "dependency hell".
	(http://en.wikipedia.org/wiki/Dependency_hell)

	The gnomad2 application calls upon the dynamic linker in Linux to
	resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
	(ELF symbol, or link point or whatever you want to call them, a
	symbol is a label on a memory address that the linker shall
	resolve from label to actual address.)
	For generic information on this subject see the INSTALL file and
	this Wikipedia page:

	http://en.wikipedia.org/wiki/Library_(computing)

	When Linux /lib/ld-linux.so.X is called to link the symbols compiled
	into gnomad2 (or any other executable using libmtp), it examines the
	ELF file for the libmtp.so.X file it finds first and cannot resolve
	the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
	problem witj) from it, since it's probably not there. There are many
	possible causes of this symbol breakage:

	1) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
	whatever) that do not match up. Typical cause: your gnomad2 package was
	built against a newer version of libmtp than what's installed on your
	machine. Another typical cause: you installed a package you found on
	the web, somewhere, the dependency resolution system did not protest
	properly (as it should) or you forced it to install anyway, ignoring
	some warnings.

	2) You compiled libmtp and/or gnomad2 from source, installing both or
	either in /usr/local/lib and /usr/local/bin. This means at compile-time
	gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
	depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
	order to resolve the symbols. This loader will look into the file
	/etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
	paths to libraries to be used for resolving the symbols. If you have
	some older version of libmtp in e.g. /usr/lib (typically installed by a
	package manager) it will take precedence over the new version you just
	installed in /usr/local/lib and the newly compiled library in
	/usr/local/lib will not be used, resulting in this error message.

	3) You really did install the very latest versions (as of writing libmtp
	0.1.5 and gnomad2 2.8.11) from source and there really is no
	pre-installed package of either on your machine. In that case I'm
	totally lost, I have no idea what's causing this.

	Typical remedies:

	1) If you don't want to mess around with your system and risk these
	situations, only use pre-packaged software that came with the
	distribution or its official support channels. If it still breaks,
	blame your distribution, they're not packaging correctly. Relying on
	properly packaged software and not installing things yourself is the
	Linux solution to the "dependency hell" problem.

	2) Read about dynamically linked library handling until the stuff I wrote
	about in the previous list sounds like music to your ears, inspect
	your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
	/etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
	YaST or whatever your distribution uses, compile libmtp and gnomad2
	(or whatever) from source only and you will be enlighted.

	I don't know if this helps you, it's the best answer we can give.