/*
  _  _                                                                       *
  _||_                                                                       *
   ||                                                                        *
                                                                             *
                                                     folkert@feedface.com   */



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



#ABOUT
##############################################################################
pod2sql enables you to import your ipod music metadata into a mysql database.
the idea is to upload the itunesDB file from your ipod to your web server, 
import the data into the db and then issue querys of whatever form wanted in 
PHP. all metadata strings are converted and stored as web-friendly UTF-8.



#REQUIREMENTS
##############################################################################
to build and run pod2sql, you need:
 + GNU libiconv [http://www.gnu.org]
 + libmysql     [http://www.mysql.com]

to use pod2sql, you need:
 + mysqld database server [http://www.mysql.com]



#BUILDING
##############################################################################
to build pod2sql, see 'make help'. basically, you need to set your include
and linker paths for libiconv and libmysql via $INCS and $LIBS. if you build
for a bigendian architecture [most non-pcs are], you need to define BIGENDIAN
via CFLAGS or in def.h



#PRECONFIGURATION
##############################################################################
you need to prepare the database to use on the mysld. also, at the moment, the
tables need to be created before running pod2sql for the first time. this can
easily be done via the pod2sql.tables.dump file supplied. just pipe the 
content into mysql via
mysql < -u$USER -p$PASS $DBASE < path/to/itunes.dbdump



#RUNNING
##############################################################################
the command syntax is
pod2sql [-H dbhost] [-P dbport] [-u dbuser] [-p dbpass] [-d dbase] itunesdb 
where 
  dbhost: the host where mysqld is running ['localhost' by default]
  dbport: the port on which mysqld is listening [MYSQL_PORT by default]
  dbuser: the mysql user as which to connect to mysql
  dbpass: the password to use when connecting to mysql
  dbbase: the database to use ['itunesdb' by default]
  itunesdb: the file to read. 
    this file is found on the ipod as iPod_Control/iTunes/iTunesDB



#USING
##############################################################################
the database can be queried either directly or with the php functions in
itunes.php. 
the structure of the database is as such:

+-------+   +--------+
| album |   | artist |
+-------+   +-+------+
         \    |
           +--+---+   +-----------+   +----------+
           + song +---+ songXlist +---+ playlist |
           +--+---+   +-----------+   +----------+
         /    |
+-------+   +-+--------+
| genre |   | composer |
+-------+   +----------+

if you plan to use the db data directy, be advised that anything read from
the db should be passed to htmlspecialchars() before printing HTML, else
certain song names could destroy your page layout :)



itunes.php offers the following functions, which all print HTML with
links into the other functions. 
function printAlbum($id)
function printAlbums()
function printPlaylist($id)
function printPlaylists()
function printSong($id)
function printSongs()
function printArtist($id)
function printArtists()
function printComposer($id)
function printComposers()
function printGenre($id)
function printGenres()
function printSummary()

itunes.html contains a standard setup to pass the $_GET variables to PHP.
itunes.css contains styles used by itunes.php.
both files should be passed through PHP before being delivered to the 
browser.




#RIGHTS
##############################################################################
pod2sql is [c] folkert@feedface.com [Folkert Saathoff]
it is published under the GNU Public Licence, see COPYING for details.