README.sqlite

* Summary

For things to work with an iPod Nano 5G or an iPhone/iTouch, you need
  - an iPod_Control/Device/SysInfoExtended file (Nano5G) or
  - an iTunes_Control/Device/SysInfoExtended file
This file should be created when the device is plugged in. If not, you can 
generate it manually using ipod-read-sysinfo-extended (passing the device UUID 
as an argument for an iPhone/iPod Touch and the USB bus and device number for
a Nano 5G). On a Nano5G, passing the device node (/dev/sdb) to
ipod-read-sysinfo-extended won't work. On a Nano5G, SysInfoExtended should be 
a few dozen kilobytes in size.

You also need a database generated by iTunes on your iPod when you first plug
it in. When libgpod reads this database, it will generate
  - an iPod_Control/Device/HashInfo file (Nano5G) or
  - an iTunes_Control/Device/HashInfo file (iPhone/iPod Touch)
which is required to write to the device.



* sqlite

New iPod models (iPhone/iPod Touch on the one hand, Nano 5G on the other hand)
contain both a compressed version of the usual iTunesDB (the iTunesCDB file)
and sqlite databases. The iTunesCDB file is used by iTunes while the sqlite
databases are used by the device. The sqlite databases use the .itdb extension
and can be found in iPod_Control/iTunes/iTunes Library/
(iTunes_Control/iTunes/iTunes Library/ on devices using the iPhone OS). Both
use some kind of checksum.

The iTunesCDB file is checksummed either with a hash58 (old hash introduced
with the first iPod Classic and the Nano 3g) or a hash72 (new hash introduced
with iPhone OS 2.x). The hash58 is used on the Nano 5G while the hash72 is
used on the iPhone/iPod Touch.

The sqlite databases are checksummed through the use of a .cbk file. This file
only checksums the content of the Location.itdb sqlite database and uses the 
hash72 on the iPhone/iPod Touch and the Nano 5G.


* HashInfo

The HashInfo file can be found in iPod_Control/Device/HashInfo
(iTunes_Control/Device/HashInfo for an iPhone/iPod Touch). At the moment, 
it's not known how to generate a checksum for the iPod database from scratch.
However, for a given iPod, we can extract the necessary data from a database
generated by iTunes to be able to generate a checksum for any other database 
for this iPod.
libgpod extracts this data the first time it reads a database on an iPod (so
it assumes this database was generated by iTunes) and dumps it to the HashInfo
file (very simple format, see the struct Hash78Info in src/itdb_hash72.c).
Then libgpod can reuse the information from that file to write valid databases
for the iPod the HashInfo was generated on.


* SysInfoExtended

The SysInfoExtended file is stored in iPod_Control/Device/SysInfoExtended
(iTunes_Control/Device/SysInfoExtended on iPhone/iPod Touch). This file isn't
a standard iPod file, it's generated using some data available on the iPod
and dumped there because it's more convenient for libgpod. It's an XML file
containing lots of data about the iPod (serial number, support image and video
formats, ...). libgpod installs a HAL/udev callout to automatically generate
this file when an iPod is plugged in, but it can also be done manually by 
using the ipod-read-sysinfo-extended tool.
This file is required on the Nano 5G because it contains SQL commands that 
have to be run to generate sqlite databases that the device will be able to 
handle.
The iPhone/iPod Touch need similar SQL commands to be run, but they are not
stored in SysInfoExtended, they are extracted from the device when needed.


On the iPhone/iPod Touch, the data for the SysInfoExtended file can be
obtained by asking for the right lockdown key through the usbmux daemon.
On the Nano5G, things are a bit more tricky. Older iPods models used to 
make that data available through a SCSI inquiry command. This command works
on the Nano5G too, but it returns really partial data (no SQL post-process
commands, no artwork format information, ...). The full data can be obtained
through an USB Control command (see tools/ipod-usb.c for more details).