## RBExtDB

RBExtDB — store for external metadata such as album art

## Synopsis

    enum                RBExtDBSourceType;
    struct              RBExtDB;
    struct              RBExtDBClass;
    void                (*RBExtDBRequestCallback)           (RBExtDBKey *key,
                                                             const char *filename,
                                                             GValue *data,
                                                             gpointer user_data);
    RBExtDB *           rb_ext_db_new                       (const char *name);
    char *              rb_ext_db_lookup                    (RBExtDB *store,
                                                             RBExtDBKey *key);
    gboolean            rb_ext_db_request                   (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBRequestCallback callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);
    void                rb_ext_db_store_uri                 (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBSourceType source_type,
                                                             const char *uri);
    void                rb_ext_db_store                     (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBSourceType source_type,
                                                             GValue *data);
    void                rb_ext_db_store_raw                 (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBSourceType source_type,
                                                             GValue *data);

## Description

This class simplifies searching for and providing external metadata such as album art or lyrics. A metadata provider connects to a signal on the database and in response provides a URI, a buffer containing the data, or an object representation of the data (such as a GdkPixbuf). A metadata requestor calls rb_ext_db_request and specifies a callback, or alternatively connects to a signal to receive all metadata as it is stored.

## Details

### enum RBExtDBSourceType

    typedef enum {
    	RB_EXT_DB_SOURCE_NONE,		/* nothing */
    	RB_EXT_DB_SOURCE_SEARCH, /* found by external search */
    	RB_EXT_DB_SOURCE_EMBEDDED, /* embedded in media itself */
    	RB_EXT_DB_SOURCE_USER,		/* provided by user (eg image in same dir) */
    	RB_EXT_DB_SOURCE_USER_EXPLICIT /* provided explicitly by user */
    } RBExtDBSourceType;

`RB_EXT_DB_SOURCE_NONE` |
`RB_EXT_DB_SOURCE_SEARCH` |
`RB_EXT_DB_SOURCE_EMBEDDED` |
`RB_EXT_DB_SOURCE_USER` |
`RB_EXT_DB_SOURCE_USER_EXPLICIT` |

### struct RBExtDB

    struct RBExtDB {
    	GObject parent;

    	RBExtDBPrivate *priv;
    };

### struct RBExtDBClass

    struct RBExtDBClass {
    	GObjectClass parent;

    	/* requestor signals */
    	void		(*added) (RBExtDB *store,
    					 RBExtDBKey *key,
    					 const char *filename,
    					 GValue *data);

    	/* provider signals */
    	gboolean (*request) (RBExtDB *store,
    					 RBExtDBKey *key,
    					 guint64 last_time);

    	/* data format conversion signals */
    	GValue * (*store) (RBExtDB *store,
    					 GValue *data);
    	GValue * (*load)		(RBExtDB *store,
    					 GValue *data);
    };

### RBExtDBRequestCallback ()

    void                (*RBExtDBRequestCallback)           (RBExtDBKey *key,
                                                             const char *filename,
                                                             GValue *data,
                                                             gpointer user_data);

### rb_ext_db_new ()

    RBExtDB *           rb_ext_db_new                       (const char *name);

Provides access to a metadata store instance.

`name` : | name of the metadata store
Returns : | named metadata store instance

### rb_ext_db_lookup ()

    char *              rb_ext_db_lookup                    (RBExtDB *store,
                                                             RBExtDBKey *key);

Looks up a cached metadata item.

`store` : | metadata store instance
`key` : | metadata lookup key
Returns : | name of the file storing the cached metadata item

### rb_ext_db_request ()

    gboolean            rb_ext_db_request                   (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBRequestCallback callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);

Requests a metadata item. If the item is cached, the callback will be called synchronously. Otherwise, metadata providers will provide results asynchronously.

`store` : | metadata store instance
`key` : | metadata lookup key
`callback` : | callback to call with results
`user_data` : | user data to pass to the callback
`destroy` : | destroy function for `user_data`
Returns : | `TRUE` if results may be provided after returning

### rb_ext_db_store_uri ()

    void                rb_ext_db_store_uri                 (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBSourceType source_type,
                                                             const char *uri);

Stores an item identified by `uri` in the metadata store so that lookups matching `key` will return it.

`store` : | metadata store instance
`key` : | metadata storage key
`source_type` : | metadata source type
`uri` : | URI of the item to store. [allow-none]

### rb_ext_db_store ()

    void                rb_ext_db_store                     (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBSourceType source_type,
                                                             GValue *data);

Stores an item in the metadata store so that lookups matching `key` will return it. `data` should contain an object that must be transformed using the RBExtDB::store signal before being stored. For example, the album art cache expects GdkPixbuf objects here, rather than buffers containing JPEG encoded files.

`store` : | metadata store instance
`key` : | metadata storage key
`source_type` : | metadata source type
`data` : | data to store. [allow-none]

### rb_ext_db_store_raw ()

    void                rb_ext_db_store_raw                 (RBExtDB *store,
                                                             RBExtDBKey *key,
                                                             RBExtDBSourceType source_type,
                                                             GValue *data);

Stores an item in the metadata store so that lookpus matching `key` will return it. `data` should contain the data to be written to the store, either as a string or as a GByteArray.

`store` : | metadata store instance
`key` : | metadata storage key
`source_type` : | metadata source type
`data` : | data to store. [allow-none]