Photo database

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

## Synopsis

                        Itdb_PhotoDB;
    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);
    gboolean            itdb_photodb_write                  (Itdb_PhotoDB *photodb,
                                                             GError **error);
    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);
    void                itdb_photodb_remove_photo           (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             Itdb_Artwork *photo);
                        Itdb_PhotoAlbum;
    void                itdb_photodb_photoalbum_free        (Itdb_PhotoAlbum *album);
    Itdb_PhotoAlbum *   itdb_photodb_photoalbum_new         (const gchar *albumname);
    void                itdb_photodb_photoalbum_add         (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             gint pos);
    void                itdb_photodb_photoalbum_unlink      (Itdb_PhotoAlbum *album);
    Itdb_PhotoAlbum *   itdb_photodb_photoalbum_create      (Itdb_PhotoDB *db,
                                                             const gchar *albumname,
                                                             gint pos);
    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);
    void                itdb_photodb_photoalbum_remove      (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             gboolean remove_pics);

## 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()`, e.g. for an 80 GB 6th generation iPod Video, you would use:

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

See itdb_device.c for a list of supported models.

The model number will be saved on the iPod when the PhotoDB is written (`itdb_photodb_write()` calls `itdb_device_write_sysinfo()`).

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_PhotoDB

    typedef struct {
        GList *photos;
        GList *photoalbums;
        Itdb_Device *device;
        /* 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;

Structure representing an iTunes Photo database

GList *`photos`; | A list of photos in the database (Itdb_Artwork)
GList *`photoalbums`; | A list of albums in the database (Itdb_PhotoAlbum)
Itdb_Device *`device`; | iPod device info (Itdb_Device)
gint32 `reserved_int1`; | Reserved for future use
gint32 `reserved_int2`; | Reserved for future use
gpointer `reserved1`; | Reserved for future use
gpointer `reserved2`; | Reserved for future use
guint64 `usertype`; | For use by application
gpointer `userdata`; | For use by application
ItdbUserDataDuplicateFunc `userdata_duplicate`; | A function to duplicate userdata
ItdbUserDataDestroyFunc `userdata_destroy`; | A function to free userdata

Since 0.4.0

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

Since 0.4.2

### itdb_photodb_free ()

    void                itdb_photodb_free                   (Itdb_PhotoDB *photodb);

Free the memory taken by `photodb`.

`photodb` : | an Itdb_PhotoDB

Since 0.4.0

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

Since 0.4.0

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

Since 0.4.0

### 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`, `GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE`, `GDK_PIXBUF_ROTATE_UPSIDEDOWN`, AND `GDK_PIXBUF_ROTATE_CLOCKWISE`.

`db` : | the Itdb_PhotoDB to add the photo to
`filename` : | path of 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.

Since 0.4.0

### 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`, `GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE`, `GDK_PIXBUF_ROTATE_UPSIDEDOWN`, AND `GDK_PIXBUF_ROTATE_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.

Since 0.4.0

### 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`, `GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE`, `GDK_PIXBUF_ROTATE_UPSIDEDOWN`, AND `GDK_PIXBUF_ROTATE_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.

Since 0.5.0

### itdb_photodb_remove_photo ()

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

Removes a 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.

### Note

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

Since 0.4.0

### Itdb_PhotoAlbum

    typedef struct {
        Itdb_PhotoDB *photodb;
        gchar *name;
        GList *members;
        guint8 album_type;
        guint8 playmusic;
        guint8 repeat;
        guint8 random;
        guint8 show_titles;
        guint8 transition_direction;
        gint32 slide_duration;
        gint32 transition_duration;
        gint64 song_id;
        gint32 unk024;
        gint16 unk028;
        gint32 unk044;
        gint32 unk048;
        /* 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;

Structure representing an iTunes Photo Album

Itdb_PhotoDB *`photodb`; | A pointer to the Itdb_PhotoDB (for convenience)
gchar *`name`; | The name of photoalbum in UTF8
GList *`members`; | A list of photos in album (Itdb_Artwork)
guint8 `album_type`; | The album type. 0x01 for master (Photo Library), 0x02 for a normal album. (4 and 5 have also been seen.)
guint8 `playmusic`; | Play music during slideshow
guint8 `repeat`; | Repeat the slideshow
guint8 `random`; | Show slides in random order
guint8 `show_titles`; | Show slide captions
guint8 `transition_direction`; | Transition direction. 0=none, 1=left-to-right, 2=right-to-left, 3=top-to-bottom, 4=bottom-to-top
gint32 `slide_duration`; | Slide duration in seconds
gint32 `transition_duration`; | Transition duration, in milliseconds
gint64 `song_id`; | The `dbid2` of a track to play during slideshow
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
gint32 `album_id`; | Unique integer for each playlist. This is set automatically when the PhotoDB is written.
gint32 `prev_album_id`; | The id of the previous playlist. This is set automatically when the PhotoDB is written.
gint32 `reserved_int1`; | Reserved for future use
gint32 `reserved_int2`; | Reserved for future use
gpointer `reserved1`; | Reserved for future use
gpointer `reserved2`; | Reserved for future use
guint64 `usertype`; | For use by application
gpointer `userdata`; | For use by application
ItdbUserDataDuplicateFunc `userdata_duplicate`; | A function to duplicate userdata
ItdbUserDataDestroyFunc `userdata_destroy`; | A function to free userdata

Since 0.4.0

### itdb_photodb_photoalbum_free ()

    void                itdb_photodb_photoalbum_free        (Itdb_PhotoAlbum *album);

Frees the memory used by `album`

`album` : | an Itdb_PhotoAlbum

### itdb_photodb_photoalbum_new ()

    Itdb_PhotoAlbum *   itdb_photodb_photoalbum_new         (const gchar *albumname);

Creates an empty Itdb_PhotoAlbum named `albumname`

`albumname` : | name of the new album
Returns : | the new Itdb_PhotoAlbum, free it with `itdb_photodb_photoalbum_free()` when no longer needed

### itdb_photodb_photoalbum_add ()

    void                itdb_photodb_photoalbum_add         (Itdb_PhotoDB *db,
                                                             Itdb_PhotoAlbum *album,
                                                             gint pos);

Adds `album` to `db->photoalbums` at position `pos` (or at the end if pos is -1).The `ib` gets ownership of the `album` and will take care of freeing the memory it uses when it's no longer necessary.

`db` : | an Itdb_PhotoDB
`album` : | an Itdb_PhotoAlbum
`pos` : | position of the album to add

### itdb_photodb_photoalbum_unlink ()

    void                itdb_photodb_photoalbum_unlink      (Itdb_PhotoAlbum *album);

Removes `album` from the Itdb_PhotoDB it's associated with, but do not free memory. `album->photodb` is set to NULL.

`album` : | an Itdb_PhotoAlbum

### 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 to append at the end).
Returns : | the album which was created and added.

Since 0.4.2

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

Since 0.4.2

### 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

Since 0.4.2

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

### Note

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.

Since 0.4.2