=======================================================================
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.

It automatically converts PNG and PLIST files when they are copied from
the iPod to the PC.


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

For the VS2005 version:

    * 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

For the VS2003 version:

    * msvcp71.dll and msvcr71.dll


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

1) Normally all you have to do is to open the .zip file with Total Commander
   and it will self-install.

* A pop-up will open asking you whether you want to install the plug-in or
  not, answer "Yes".
  
* If another version was installed before, you have to choose whether you 
  want to overwrite the files or to install the plug-in into another 
  directory. In the case you install an update or re-install the plug-in, 
  simply choose to overwrite.
  
  Note that you will be able to overwrite the plug-in even if you have 
  opened a connection on the iPod. The new version will correctly replace 
  the previous one and you should be able to go on browsing on the device.
  
* Otherwise an installation directory is suggested, you may modify it if 
  you want. Click on OK when you are ready to install the plug-in.

2) If for some reason the self-install doesn't trigger, proceed as follows to 
   install it manually:

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

3) In both methods a new plug-in will be shown 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 can rename it by clicking on 
  "Rename" if you wish. You can also do that later from the configuration 
  menu.

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

This will not remove the files in the Total COmmander installation
directory, however. You can re-install the plug-in from those files
or from the original .zip.


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 1.1 (23-Jan-2007)

    Local file-to-file copy on the iPod. This is only for the sake of
    completeness, it is recommended to use an iPod native application to
    copy files locally to preserve the permission flags. Doing so with
    Total Commander will result in resetting those permission flags,
    because of the limitations explained above.
    
    Ability to copy files bigger than 4GB (not fully tested).

* Version 1.0 (30-Dec-2007)

    Plist translation code has been redone from scratch, based on the Apple 
    CoreFoundation references. It's now simpler - at least as much as the 
    Apple way would allow... - and doesn't leak memory like the previous 
    one which was based on an existing hack.

* Version 0.4 (23-Dec-2007)

    Self-install version.

* Version 0.3 (20-Dec-2007)

    Added conversion of property list binary files to text files.

    Most of the plist files originally on the iPod - used or generated
    by the original applications - are stored in binary format to save
    space. The plug-in now automatically converts them to text (XML)
    when they are transferred from the iPod to the PC.
    
    This is also done when they are compared, viewed or edited, since this 
    implies a copy to a temporary file on the PC.

* 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. 
    The plug-in automatically generates 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. 

* Version 0.1 (10-Dec-2007)

    First public test version.

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/
