Photo database

## Photo database Photo database — Functions to create, read, write the photo database |

## Synopsis

                        Itdb_PhotoAlbum;
                        Itdb_PhotoDB;
    Itdb_Artwork*       itdb_photodb_add_photo              (Itdb_PhotoDB *db,
                                                             const gchar *filename,
                                                             gint position,
                                                             gint rotation,
                                                             GError **error);
    Itdb_Artwork*       itdb_photodb_add_photo_from_data    (Itdb_PhotoDB *db,
                                                             const guchar *image_data,
                                                             gsize image_data_len,
                                                             gint position,
                                                             gint rotation,
                                                             GError **error);
    Itdb_Artwork*       itdb_photodb_add_photo_from_pixbuf  (Itdb_PhotoDB *db,
                                                             gpointer pixbuf,
                                                             gint position,
                                                             gint rotation,
                                                             GError **error);
    Itdb_PhotoDB*       itdb_photodb_create                 (const gchar *mountpoint);
    void                itdb_photodb_free                   (Itdb_PhotoDB *photodb);
    Itdb_PhotoDB*       itdb_photodb_parse                  (const gchar *mp,
                                                             GError **error);
    void                itdb_photodb_photoalbum_add_photo   (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             Itdb_Artwork *photo,
                                                             gint position);
    Itdb_PhotoAlbum*    itdb_photodb_photoalbum_by_name     (Itdb_PhotoDB *db,
                                                             const gchar *albumname);
    Itdb_PhotoAlbum*    itdb_photodb_photoalbum_create      (Itdb_PhotoDB *db,
                                                             const gchar *albumname,
                                                             gint pos);
    void                itdb_photodb_photoalbum_remove      (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             gboolean remove_pics);
    void                itdb_photodb_remove_photo           (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             Itdb_Artwork *photo);
    gboolean            itdb_photodb_write                  (Itdb_PhotoDB *photodb,
                                                             GError **error);

## Description

These functions are for creating, reading, and writing the photo database.

Overview of using the Photo database:

`itdb_photodb_parse()`: Read an existing PhotoDB.

`itdb_photodb_create()`: Create a new Itdb_PhotoDB structure. The Photo Library Album is (first album) is created automatically.

`itdb_photodb_add_photo()`, `itdb_photodb_add_photo_from_data()`: Add a photo to the PhotoDB (from file or from a chunk of memory). It is automatically added to the Photo Library Album (first album), which is created if it does not exist already.

`itdb_photodb_photoalbum_create()`: Create and add a new photoalbum.

`itdb_photodb_photoalbum_add_photo()`: Add a photo (Itdb_Artwork) to an existing photoalbum.

`itdb_photodb_photoalbum_remove()`: Remove an existing photoalbum. Pictures can be kept in the Photo Library or automatically removed as well.

`itdb_photodb_remove_photo()`: Remove a photo either from a photoalbum or completely from the database.

`itdb_photodb_write()`: Write out your PhotoDB.

`itdb_photodb_free()`: Free all memory taken by the PhotoDB.

`itdb_photodb_photoalbum_by_name()`: Find the first photoalbum with a given name or the Photo Library Album if called with no name.

If you cannot add photos because your iPod is not recognized, you may have to set the iPod model by calling

itdb_device_set_sysinfo (db->device, "ModelNumStr", model);

For example, "MA450" would stand for an 80 GB 6th generation iPod Video. See itdb_device.c for a list of supported models.

This information will be written to the iPod when the PhotoDB is saved (`itdb_device_write_sysinfo()` is called).

Have a look at the test-photos test program in the tests/ directory of the libgpod source for an example of how to use the interface.

## Details

### Itdb_PhotoAlbum

    typedef struct {
        gchar *name;                 /* name of photoalbum in UTF8            */
        GList *members;              /* photos in album (Itdb_Artwork *)      */
        guint8 album_type;           /* 0x01 for master (Photo Library),
    				    0x02 otherwise (sometimes 4 and 5)    */
        guint8 playmusic;            /* play music during slideshow (from
    				    iPhoto setting)                       */
        guint8 repeat;               /* repeat the slideshow (from iPhoto
    				    setting)                              */
        guint8 random;               /* show the slides in random order
    			            (from iPhoto setting)                 */
        guint8 show_titles;          /* show slide captions (from iPhoto
    				    setting)                              */
        guint8 transition_direction; /* 0=none, 1=left-to-right,
    				    2=right-to-left, 3=top-to-bottom,
    				    4=bottom-to-top (from iPhoto setting) */
        gint32 slide_duration;       /* in seconds (from iPhoto setting)      */
        gint32 transition_duration;  /* in milliseconds (from iPhoto setting) */
        gint64 song_id;              /* dbid2 of track in iTunesDB to play
    				    during slideshow (from iPhoto setting)*/
        gint32 unk024;               /* unknown, seems to be always 0         */
        gint16 unk028;               /* unknown, seems to be always 0         */
        gint32 unk044;               /* unknown, seems to always be 0         */
        gint32 unk048;               /* unknown, seems to always be 0         */
        /* set automatically at time of writing the PhotoDB */
        gint32  album_id;
        gint32  prev_album_id;
        /* reserved for future use */
        gint32 reserved_int1;
        gint32 reserved_int2;
        gpointer reserved1;
        gpointer reserved2;
        /* below is for use by application */
        guint64 usertype;
        gpointer userdata;
        /* functions called to duplicate/free userdata */
        ItdbUserDataDuplicateFunc userdata_duplicate;
        ItdbUserDataDestroyFunc userdata_destroy;
    } Itdb_PhotoAlbum;

### Itdb_PhotoDB

    typedef struct {
        GList *photos;      /* (Itdb_Artwork *)     */
        GList *photoalbums; /* (Itdb_PhotoAlbum *)  */
        Itdb_Device *device;/* iPod device info     */
        /* reserved for future use */
        gint32 reserved_int1;
        gint32 reserved_int2;
        gpointer reserved1;
        gpointer reserved2;
        /* below is for use by application */
        guint64 usertype;
        gpointer userdata;
        /* functions called to duplicate/free userdata */
        ItdbUserDataDuplicateFunc userdata_duplicate;
        ItdbUserDataDestroyFunc userdata_destroy;
    } Itdb_PhotoDB;

### itdb_photodb_add_photo ()

    Itdb_Artwork*       itdb_photodb_add_photo              (Itdb_PhotoDB *db,
                                                             const gchar *filename,
                                                             gint position,
                                                             gint rotation,
                                                             GError **error);

Add a photo to the PhotoDB. The photo is automatically added to the first Photoalbum, which by default contains a list of all photos in the database. If no Photoalbums exist one is created automatically.

For the rotation angle you can also use the gdk constants GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND ..._CLOCKWISE.

`db` : | the Itdb_PhotoDB to add the photo to.
`filename` : | file with the photo to add.
`position` : | position where to insert the new photo (-1 to append at the end)
`rotation` : | angle by which the image should be rotated counterclockwise. Valid values are 0, 90, 180 and 270.
`error` : | return location for a GError or NULL
Returns : | a pointer to the added photo.

### itdb_photodb_add_photo_from_data ()

    Itdb_Artwork*       itdb_photodb_add_photo_from_data    (Itdb_PhotoDB *db,
                                                             const guchar *image_data,
                                                             gsize image_data_len,
                                                             gint position,
                                                             gint rotation,
                                                             GError **error);

Add a photo to the PhotoDB. The photo is automatically added to the first Photoalbum, which by default contains a list of all photos in the database. If no Photoalbums exist one is created automatically.

For the rotation angle you can also use the gdk constants GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND ..._CLOCKWISE.

`db` : | the Itdb_PhotoDB to add the photo to.
`image_data` : | chunk of memory containing the image data (for example a jpg file)
`image_data_len` : | length of above chunk of memory
`position` : | position where to insert the new photo (-1 to append at the end)
`rotation` : | angle by which the image should be rotated counterclockwise. Valid values are 0, 90, 180 and 270.
`error` : | return location for a GError or NULL
Returns : | a pointer to the added photo.

### itdb_photodb_add_photo_from_pixbuf ()

    Itdb_Artwork*       itdb_photodb_add_photo_from_pixbuf  (Itdb_PhotoDB *db,
                                                             gpointer pixbuf,
                                                             gint position,
                                                             gint rotation,
                                                             GError **error);

Add a photo to the PhotoDB. The photo is automatically added to the first Photoalbum, which by default contains a list of all photos in the database. If no Photoalbums exist one is created automatically.

For the rotation angle you can also use the gdk constants GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND ..._CLOCKWISE.

`db` : | the Itdb_PhotoDB to add the photo to.
`pixbuf` : | a GdkPixbuf to use as the image data
`position` : | position where to insert the new photo (-1 to append at the end)
`rotation` : | angle by which the image should be rotated counterclockwise. Valid values are 0, 90, 180 and 270.
`error` : | return location for a GError or NULL
Returns : | a pointer to the added photo.

### itdb_photodb_create ()

    Itdb_PhotoDB*       itdb_photodb_create                 (const gchar *mountpoint);

Creates a new Itdb_PhotoDB. If mountpoint is NULL, you will have to set it manually later by calling `itdb_device_set_mountpoint()`.

`mountpoint` : | mountpoint or NULL.
Returns : | a newly created Itdb_PhotoDB to be freed with `itdb_photodb_free()` when it's no longer needed. The Photo Library Album is created automatically.

### itdb_photodb_free ()

    void                itdb_photodb_free                   (Itdb_PhotoDB *photodb);

Free the memory taken by `photodb`.

`photodb` : | an Itdb_PhotoDB

### itdb_photodb_parse ()

    Itdb_PhotoDB*       itdb_photodb_parse                  (const gchar *mp,
                                                             GError **error);

Parses the photo database of an iPod mounted at `mp`.

`mp` : | mountpoint of the iPod
`error` : | will contain the error description when an error occured.
Returns : | the imported PhotoDB or NULL in case of an error.

### itdb_photodb_photoalbum_add_photo ()

    void                itdb_photodb_photoalbum_add_photo   (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             Itdb_Artwork *photo,
                                                             gint position);

Adds a photo already in the library to the specified album `album`. Photos are automatically added to the first album (Photo Library) when calling `itdb_photodb_add_photo()` or `itdb_photodb_add_photo_from_data()`, so you don't have to use this function to add them there.

`db` : | the Itdb_PhotoDB to act on
`album` : | the Itdb_PhotoAlbum to add the photo to
`photo` : | a pointer to the photo (Itdb_Artwork) to add to the album
`position` : | position where to insert the new photo (-1 to append at the end)

### itdb_photodb_photoalbum_by_name ()

    Itdb_PhotoAlbum*    itdb_photodb_photoalbum_by_name     (Itdb_PhotoDB *db,
                                                             const gchar *albumname);

Find the first photoalbum with a given name or the Photo Library Album if called with no name.

`db` : | the Itdb_PhotoDB to retrieve the album from
`albumname` : | the name of the photoalbum to get or NULL for the master photoalbum.
Returns : | a pointer to the first photoalbum named `albumname`, else NULL

### itdb_photodb_photoalbum_create ()

    Itdb_PhotoAlbum*    itdb_photodb_photoalbum_create      (Itdb_PhotoDB *db,
                                                             const gchar *albumname,
                                                             gint pos);

Create and add a new photoalbum.

`db` : | The database to create a new album in
`albumname` : | the name of the new album
`pos` : | position where to insert the newly created album (-1 for append to end).
Returns : | the album which was created and added.

### itdb_photodb_photoalbum_remove ()

    void                itdb_photodb_photoalbum_remove      (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             gboolean remove_pics);

Remove `album` from the Photo Database. If remove_pics is TRUE, remove all photos contained in `album` from the Photo Database.

Memory used by the removed album will be freed and the album cannot be accessed any more.

`db` : | the Itdb_PhotoDB to apply changes to
`album` : | the album to be removed from the database
`remove_pics` : | TRUE to remove pics in that album permanently from the database.

### itdb_photodb_remove_photo ()

    void                itdb_photodb_remove_photo           (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             Itdb_Artwork *photo);

Remove photo. If `album` is not the first photoalbum, the photo will be removed from that album only. If `album` is NULL or the first photoalbum (Photo Library), the photo will be removed from all albums and the Itdb_PhotoDB.

`photo` will be freed and can no longer be used if removed from the first photoalbum.

`db` : | the Itdb_PhotoDB to remove the photo from
`album` : | the album to remove the photo from. If album is NULL, then it will first be removed from all photoalbums and then from the photo database as well.
`photo` : | Itdb_Artwork (photo) to remove.

### itdb_photodb_write ()

    gboolean            itdb_photodb_write                  (Itdb_PhotoDB *photodb,
                                                             GError **error);

Write out a PhotoDB.

FIXME: error is not set yet.

`photodb` : | the Itdb_PhotoDB to write to disk
`error` : | return location for a GError or NULL
Returns : | TRUE on success, FALSE on error, in which case `error` is set accordingly.