                      MTPSYNC (c) 2008-2009 by nickk
                      ______________________________


CONTENTS
________

 1. Introduction
 2. Installation
 3. Usage
 4. Bugs And Limitations
 5. LICENSE
 6. Author
 7. Changelog

1. Introduction
_______________

MTPSYNC is a simple command line tool to transfer data to/from USB MTP 
device (i.e. media player, cell phone, digital photo device and so on).

2. Installation
_______________

MTPSYNC makes use of usbcalls.dll and usbresmg.sys. So you must have proper
installation of this stuff.
There are several builds of usbcalls.dll and usbresmg.sys which differs by the
number of bugs implemented. I suggest you to use the Froloff's builds included
in this package. Although its not bugless, but the most usable i've ever seen.
For info about usbcalls.dll and usbresmg.sys installation dig the internet. 
Finally, your config.sys should contain smth like this:

BASEDEV=USBUHCD.SYS
BASEDEV=USBUHCD.SYS
BASEDEV=USBUHCD.SYS
BASEDEV=USBUHCD.SYS
BASEDEV=USBEHCD.SYS
BASEDEV=USBD.SYS /REQ:USBUHCD$,USBOHCD$,USBEHCD$
DEVICE=D:\OS2\BOOT\USBRESMG.SYS

And your LIBPATH should contain matching usbcalls.dll

You'll also need libc063.dll runtime. 
You can find it there ftp://ftp.netlabs.org/pub/gcc/libc-0.6.3-csd3.zip

3. Usage
________

Well, running mtpsync.exe without params you got quite 
selfexplanatory help:

 --print                Print available objects on device
 --battery              Print battery level
 --synclocal            Dump content of MTP device to local directory
 --delete <id/path>     Delete object by given id or path
 --up <path>            Upload path to device
 --down <id/path>       Download object by given path or id from devi
 --cp <cp>              Set codepage of MP3 id tags
 --dir <dir>            Set local directory to work with
 --vendor <vendor_id>   Add vendor_id to supported list
 --product <product_id> Add product_id to supported list
 --storage <storage_id> Select storage ID to work with (0 - default)
 --storages             Print list of available storages

mtpsync works with full or partial local mirror of MTP device on the local disk.
It seeks this mirror in local directory. You can specify another directory
to work with with --dir command or setting MTPROOT environment variable 
(i.e. in your config.sys).
It advisable first to do mtpsync --synclocal to create local mirror. 
Then you can just add or edit files within the directory structure you got 
with --synclocal and issue --up command to upload your changes or new files to
device.

--delete, --up and --down are all recursive. So, if you put a directory as an
path there all the subdirs and files within this directory will be 
deleted, uploaded or downloaded respectively.

There are five main classes of objects which MTP device handles:

1. Directory/folder. Well, you know what is it

2. File. Just a file, picture, video, smth else.

3. Music track. If an audio file - mp3, wav, ogg, etc. The music track has the 
   attributes - artist name, album name, track name, genre, year, number 
   within album.
   mtpsync tries to recognize this attributes automatically. In case of mp3 it
   reads id3 tag. Besides it parses the name of parent directory by the template:
   'Artist - Album - Year'. The data taken from the directory name prevails over
   the mp3 id3 tag data.

4. Album. Its a special object which represents an audio album. The folder with
   music tracks is not yet the album. The album object is mapped to local disc
   as <name>.alb file within the folder of this album. This file is a simple 
   text file where first line is the artist name, the rest is the track list.
   To upload a new album to mtp device just create in the folder you want to 
   upload a file named <name of album>.alb with the singe line in it - the artist 
   name. You dont need to place tracklisting there.

   Note, that although the some mtp devices displays the name of album not the 
   one you defined by alb file, but the album name of the tracks of this album.
   Hope, you understand, what i say there ;)

5. Playlist. You know what is it ;) Its mapped to simple text files which 
   contains full names of tracks withing the playlist relative to the root 
   folder of MTP device. Generally the playlists are put into 'My Playlists'
   folder. So, when you create a new playlist - put it in this foolder, 
   otherwise mtpsync wont recognize it as playlist and upload as an ordinal file.

The --cp command is useful if you have the different codepage in ID3 tags of 
your MP3 files than the system one. I.e. russian users often have CP1251 
codepage in those tags and CP866 as the system codapage. The IBM-1251 is the
default setting ;). You can use MTPCP environment variable instead of --cp.

Well, thats all of usage. Explore all the other strategies of usage of this
useful tool by yourself or donate to project if you want more readme ;)


4. Bugs And Limitations
_______________________

There are plenty. First and foremost, the usbresmg.sys/usbcalls.dll do not 
allow zero byte transfers which are quite practised in mtpsync underlying 
usb libraries. I am eager to fix it, but, although the sources available 
somewhere, i failed to find that place of availability...

Tested MTP devices (all that i have ;)) : 
Creative ZEN V Plus
Sandisk Sansa Clip
SANYO XACTI CA8


5. License
__________

Use this software for free.

And, of course:

THIS SOFTWARE IS PROVIDED BY THE AUTHOR OR CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, SEX OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE, SHIT ON CARPET OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.

6. Author
_________

 nickk, dev.nul@mail.ru

 Feel free to send author bugreports and suggestions about this great tool, but 
 first, please, make sure that your email provider accepts emails from 
 mail.ru domain. Or you may never receive the response.

 Big thanks for testing to all those brave guys who did it ;)
 Well, there are none so far...

7. Changelog
____________

0.0.1
  Initial release

0.0.2
  Added initializing of multi mode devices as MTP (you should switch such device to MTP or authomatic mode in its FW).
  Added support of multiple storages within the device.
  