Introduction:
The goal of this document is to provide an overview of the various parts/files
involved when libgpod interacts with a device. Ideally it will be helpful to
help application writers/distributors/... figure out what's going wrong when
trying to interact with an iPod-like device.
Please note that not all devices need all these steps (especially the
hash58/hash72 stuff and the sqlite databases), see the table at the end for
more details
Overview:
* device is plugged in
HAL/udev detects the insertion and runs a callout. This callout sends the
appropriate commands (raw SCSI/USB commands or special AFC command) to the
device to get an XML file describing the device capabilities (artwork formats
supported, serial number, ...) and dumps this XML file to
iPod_Control/Device/SysInfoExtended for future use by libgpod. libgpod doesn't
do it directly because sending these SCSI/USB commands might need elevated
priviledges.
* the application uses libgpod to read the device content
iPod_Control/iTunes/iTunesDB is accessed as well as a few other files. If
the device needs an hash72 (either in its iTunesDB or because it's using sqlite
databases), then the necessary information is extracted from the existing
iTunesDB to generate an iPod_Control/Device/HashInfo file (if it doesn't
exist) which will be useful to generate any hash72 we need for this device.
* the application uses libgpod to write to the device
libgpod generates an iPod_Control/iTunes/iTunesDB file. If an hash58 is needed
then the device FirewireID is used to generate it. If an hash72 is needed
then the HashInfo file is used to generate it. If the device uses sqlite
databases, they are generated as well. Post process SQL commands are then
extracted from the device (either by getting them from SysInfoExtended or by
getting them through AFC) and executed after the sqlite database generation.
These post process commands are useful to make sure the sqlite databases layout
matches what the current device firmware expects.
Glossary:
iTunesDB: binary file containing information about all the songs, playlists, ...
stored on the device. On recent devices (iPhoneOS 3.x, Nano 5g), it's replaced
by iTunesCDB which is a compressed version of iTunesDB.
sqlite: recent devices (iPhoneOS 3.x, Nano5g) use sqlite databases instead
of an iTunesDB to store song information, playlists, ... More accurately, they
have both an iTunesCDB (compressed iTunesDB) used by iTunes to know the device
content and sqlite databases used by the device. Along with these sqlite
databases, there's a .cbk file which contains checksum information and a hash72
for the sqlite data.
iPhoneOS: umbrella for iPhone-like devices, ie iPhones, iPod Touch and (likely)
iPad. On these devices, what matters is the firmware version, not the device
type.
hash58: first iTunesDB hashing scheme introduced by Apple. It appeared in the
iPod Nano Video (3g) and iPod Classic and was used by iPhoneOS 1.x. It's fully
reverse-engineered and uses the iPod FirewireID (called this way even on USB
devices) as part of the calculation.
hash72: hashing scheme that was first introduced in iPhoneOS 2.x and has then
been used on the iPod Nano with a camera (5g). It was much more complicated to
reverse engineer and is not yet 100% known. However, given a file with a valid
hash72, we can extract some hashing data to be able to generate valid hash72
hashes for any file.
iPod feature matrix:
SysInfoExtended hash58 hash72 sqlite iTunesCDB
iPod 1G no no no no no
iPod 2G no no no no no
iPod 3G no no no no no
Mini 1G no no no no no
Mini 2G no no no no no
iPod 4G yes no no no no
iPod 5G yes no no no no
Nano 1G yes no no no no
Nano 2G yes no no no no
iPod Classic yes yes no no no
Nano3G yes yes no no no
Nano4G yes yes no no no
iPhoneOS 1.x yes yes no no no
iPhoneOS 2.x yes no yes no no
Nano5G yes yes[1] yes yes yes
iPhoneOS 3.x yes no yes yes yes
[1] surprisingly, the Nano5G uses a hash58 for its iTunesCDB and a hash72
for its sqlite cbk file. iPhoneOS 3.x uses hash72 everywhere.