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

 The id of the album. 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_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