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.