/*
 * imagedb.h - declarations for image database data structures
 *
 * The image database is represented on the disk as an XML file. In memory,
 * it is represented by the abstract data type ImageDB. The database contains
 * a hierarchical folder structure, with each folder (data type ImageFolder)
 * capable of holding both images (data type Image) and subfolders.
 *
 * The data structures are modified in memory and the on-disk representation
 * is updated only when image_db_save is called.
 */


#ifndef IMAGEDB_H


/*
 * We need some system headers.
 */
#include <glib.h>


/*
 * The whole image database.
 */
typedef struct ImageDB ImageDB;


/*
 * A folder in a ImageDB.
 */
typedef struct ImageFolder ImageFolder;


/*
 * An image in a ImageFolder.
 */
typedef struct Image Image;


/*
 * Create a image database in memory. The 'filename' argument tells where
 * the on-disk representation is stored. If the file does not exist, the
 * database is considered to be empty. The file will be created when the
 * database is saved to disk with image_db_save.
 */
ImageDB *image_db_create(const gchar *filename);


/*
 * Destroy a image database data structure in memory (but don't touch the
 * on-disk representation).
 */
void image_db_destroy(ImageDB *imagedb);


/*
 * Return the current name of of the database. Return NULL if there is no
 * name.
 */
const gchar *image_db_get_name(ImageDB *imagedb);


/*
 * Set the current name of of the database.
 */
void image_db_set_name(ImageDB *imagedb, const gchar *name);


/*
 * Has the database (or any images or folders within it) been modified 
 * since it was created or last saved?
 */
gboolean image_db_is_modified(ImageDB *imagedb);


/*
 * Save the database to the disk. The filename was given as an argument
 * to image_db_create. Return -1 for error, 0 for success.
 */
gint image_db_save(ImageDB *imagedb);


/*
 * Return the root folder for the database.
 */
ImageFolder *image_db_get_root(ImageDB *image);


/*
 * Create a new folder, as child of `parent'.
 */
ImageFolder *image_folder_create(ImageFolder *parent);


/*
 * Create a new folder subtree, with images, as child of 'parent', from
 * XML data, for drag and drop purposes.
 */
ImageFolder *image_folder_create_from_xml(ImageFolder *parent, 
    	    	    	    	    	  const gchar *xml);


/*
 * Destroy a folder, and its images and subfolders, and detach it from
 * the parent.
 */
void image_folder_destroy(ImageFolder *folder);


/*
 * Return the parent folder of the current folder, or NULL if the current
 * folder is the root folder.
 */
ImageFolder *image_folder_get_parent(ImageFolder *folder);


/*
 * Return the value of an attribute of an ImageFolder. Return an emtpy string
 * (not NULL) if the folder does not have the attribute. The caller must
 * treat the returned string as read-only, and must not modify or free
 * it.
 */
const gchar *image_folder_get_attribute(ImageFolder *folder, 
    	    	    	    	    	const gchar *name);


/*
 * Set the value of an attribute of an ImageFolder. The value (and name) 
 * will be copied.
 */
void image_folder_set_attribute(ImageFolder *folder, 
    	    	    	    	const gchar *name, const gchar *value);


/*
 * Return list of sub-folders to the current folder.The list (but not the
 * ImageFolder's) must be destroyed by the caller.
 */
GList *image_folder_get_folders(ImageFolder *folder);


/*
 * Return a list with the Image's in a folder. The list (but not the
 * Images's) must be destroyed by the caller.
 */
GList *image_folder_get_images(ImageFolder *folder);


/*
 * Import an image to a folder from an image file. Return the Image object
 * that corresponds to the new image.
 */
Image *image_folder_import(ImageFolder *folder, const gchar *filename);


/*
 * Import an image to a folder from drag-and-drop image data (see
 * image_get_xml). Return the Image object that corresponds to the new
 * image.
 */
Image *image_folder_import_from_xml(ImageFolder *folder, const gchar *xml);


/*
 * Remove an image from a folder.
 */
void image_folder_remove_image(ImageFolder *folder, Image *image);


/*
 * Get folder contents (folder plus the images in it) as XML for drag 
 * and drop.
 */
gchar *image_folder_get_xml(ImageFolder *folder);


/*
 * Return the value of an attribute of an Image. Return an emtpy string
 * (not NULL) if the Image does not have the attribute. The caller must
 * treat the returned string as read-only, and must not modify or free
 * it.
 */
const gchar *image_get_attribute(Image *image, const gchar *name);


/*
 * Set the value of an attribute of an Image. The value (and name) will be 
 * copied.
 */
void image_set_attribute(Image *image, const gchar *name, const gchar *value);


/*
 * Format image information for drag-and-drop. The caller is supposed to
 * free this information.
 */
gchar *image_get_xml(Image *image);


/*
 * Unit test.
 */
gint image_unit_test(void);


#endif