README

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.

If you happen upon a device which libmtp claims it cannot
autodetect, please submit the vendor ID and device ID 
as a bug, patch or feature request on the Sourceforge
bug tracker at our homepage.


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.

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

* 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.)

* Very few devices that implement GetObjectPropList (0x9805) will
  return the entire object list if you request a list for object
  0xffffffffu. (But they should.) So we're currently not using 
  that feature.