=======================================================================
T-PoT - Total Commander file system plug-in for iPod and iPhone devices
=======================================================================

1. Purpose
----------

T-PoT is a plug-in for Total Commander allowing to browse the Apple iPod
Touch and iPhone contents via USB.


2. Requirements
---------------

T-PoT runs on Windows only, it has been tested with Total Commander 7.02a
but should be back-compatible with version 6.

The following software must be installed:

* iTunes 7.4 or later (Windows XP SP2 required).
* Microsoft .NET Framework Version 2.0 Redistributable Package (x86)
  http://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en

  Which requires the following:
  * Windows Installer 3.0 Redistributable (needs genuine Windows)
    http://www.microsoft.com/downloads/details.aspx?familyid=5FBC5470-B259-4733-A914-A956122E08E8&displaylang=en


3. Installation
---------------

* Copy T-PoT.wfx to the following directory:

    <TotalCommander>\plugins\wfx
	
  where "<TotalCommander>" is the Total Commander installation directory,
  e.g. c:\Program Files\totalcmd. You may have to create the wfx 
  subdirectory if it doesn't exist yet.

* In Total Commander, choose "Configurations" / "Options..." from the
  menu.

* In the "Configuration" window, select "Plugins", under the "Operation"
  category on the left panel.

* Click on the "Configure" button of the "File system plugins (.WFX)"
  plug-in category, on the right.

* Click the "Add" button and browse to the directory where you have
  copied the T-PoT.wfx file earlier. Select this file and click
  on the "Open" button.
  This will show a new plug-in in the "File system plugins" window.

* The default name that will show in the "Network Neighborhood" system 
  folder of Total Commander is "t-pot", but you may rename it by
  clicking on "Rename" if you wish.
  Click on "OK" when you are done, to close the "File system plugins"
  window, and OK again to close the "Configuration" window.


4. Uninstalling T-PoT
---------------------

To remove the plug-in,

* In Total Commander, choose "Configurations" / "Options..." from the
  menu.

* In the "Configuration" window, select "Plugins", under the "Operation"
  category on the left panel.

* Click on the "Configure" button of the "File system plugins (.WFX)"
  plug-in category, on the right.

* Select the plug-in, and click on the "Remove" button.


5. User Guide
-------------

To connect to the iPod Touch or iPhone, proceed as follows:

* Connect your iPod Touch or iPhone in an USB port and make sure it is
  switched on and ready. The connection can be established whether
  the device is locked or not.

* Select the "Network Neighborhood" system folder with Total Commander,
  for example by changing the left or right drive and choosing the
  last entry of the list, "\ - Network Neighborhood".
  
  You should see a "[t-pot]" directory (or another name if you renamed
  the plug-in earlier). Enter that directory and you will be in the
  uppermost directory accessible from the USB port.

Note that if your device has been jailbroken, the top directory will
be the root directory of the iPod/iPhone file system, in other words the
directory / of MacOS X (1.1.1 or 1.1.2 at the time of writing). If the
device has not been jailbroken and is in its original configuration,
the top directory will be the Media directory used by iTunes to store
the music, photos and so on, corresponding to the following directory:

	/private/var/root/Media

To transfer files from and to your iPod, use the normal commands of
Total Commander.

##########################################################################
                                 CAUTION
##########################################################################

A) Be careful about which files you write to the device and where.

Overwriting system files may render your device non operable and force
you to restore it. Doing so will make you lose all your applications
and data.

B) The USB API provided by iTunes does not allow a full visibility on the
file system of the device. Among others, the following attributes are
not accessible:

* read/write/execute permissions
* date of creation/modification/access/...
* whether the item is a soft link

Which means that if you copy from the iPod to the PC, you will lose some
part of the information. While this is not important to copy most of the
data (music, pdf files, plist files, png files, ...), this can have a
consequence if you use this plug-in for to make a backup of an entire
directory structure that includes soft links and executable files:
on transferring the structure back to the iPod, soft links will be copied
as regular files/directories, and execute permissions will be reset.

The default permissions set on files copied to the iPod/iPhone are:
* read/write for owner
* read for group and everyone

The date is set to the instant of the transfer, and files are created on
the device as regular files or directories.

A way to ensure that the file attributes are preserved is to log on the
device with an SSH session, and to make a tarball archive which can then 
be transferred by USB (which is faster). For that, your device needs
to be jailbroken.

For example, to save the contents of /var/root/Library and 
/System/Library:

* Install the BSD Subsystem on your iPod/iPhone, this application by
  Nullriver provides useful Mac OS X commands like tar and gzip.
* Log in as root using an SSH session, using WinSCP or PuTTY for instance.
* Type in the following commands:

	cd /tmp
	tar czf backup.tgz /var/root/Library /System/Library

* Log off when the process has finished creating the archive.
* Copy the /tmp/backup.tgz file to your PC with Total Commander.
* Delete the /tmp/backup.tgz on your iPod or iPhone.

Restoring the whole archive or part of it can be done by using a similar
procedure: copying back the tarball to /etc and using tar to extract
the desired contents.

THIS IS AN EXAMPLE ONLY to illustrate the procedure, once again make sure
you know what you are doing and choose the directories you save/restore
carefully. Overwriting system files might force you to restore your
device thus losing all its applications and data!

##########################################################################


6. Known Issues
---------------

* "Create new text file and load into editor" (Shift-F4) doesn't work as
  expected, it will create a file on the other panel (left vs right) if
  it points to the PC file system. This is an issue on the side of
  Total Commander and its author is working on the problem.

* "Synchronize Dirs" shows files as unknown (?) in a comparison even if
  the date is ignored and the comparison is done by contents.

* No version showing in the T-PoT.wfx file yet, no configuration panel.

* Permissions and date are lost during the transfer. See the CAUTION
  note above. This is a limitation of the API provided by iTunes and
  there is no known work-around. If you happen to know one, please let
  me know.

There is no public repository or issue tracking database for the moment,
I will set up one shortly. This is currently a beta version under test,
if you have remarks or problems using it, please sent a PM to Scythal
on the following site:

http://www.ipodtouchfans.com/forums/


7. History
----------

* Version 0.1 (10-Dec-2007)

	First public test version.

* Version 0.2 (11-Dec-2007)

	Added conversion of PNG image files.

	Apple uses a non-compliant PNG format to store the images on the iPod. A 
	converter is being integrated in the plug-in to generate proper PNG 
	files when they are copied from the iPod to the PC.
	
	For some reason, the PNG images found in the original applications have 
	a new chunk type "CgBl" which signals different modifications in the 
	IDAT chunks:
	
	    * No header/footer in the zlib-deflated data,
	    * Inversion of the red and blue channels. 
	
	Besides, this CgBl chunk is found before the IHDR chunk, which should 
	normally be in the first position. 

8. Licence
----------

Copyright (c) 2007, Scythal
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the software nor the names of its contributors may be 
      used to endorse or promote products derived from this software without 
      specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ITS AUTHOR ``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 AUTHOR 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, OR PROFITS; OR BUSINESS 
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGE.


9. Trademark and Copyright Statements
-------------------------------------

* Apple, iPod, iPhone, iTunes and Mac OS are trademarks of Apple Computer, Inc., 
  registered in the U.S. and other countries. All rights reserved.
* Total Commander is Copyright (C) 1993-2007 by Christian Ghisler, C. Ghisler & Co.
* WinSCP is Copyright (C) 2000-2007 by Martin Prikryl.
* PuTTY is Copyright (C) 1997-2007 by Simon Tatham.

All mentioned Trademarks and Copyrights belong to their respective owners.


10. Links
---------

* Total Commander

	http://www.ghisler.com/

* Apple

	http://www.apple.com/

* WinSCP

	http://winscp.net/

* PuTTY

    http://www.chiark.greenend.org.uk/~sgtatham/putty/

