Cache

Cache — A fast SQLite cache for glyr's results

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <glyr/cache.h>

#define             GLYR_DB_FILENAME
int                 glyr_db_delete                      (GlyrDatabase *db,
                                                         GlyrQuery *query);
void                glyr_db_destroy                     (GlyrDatabase *db_object);
int                 glyr_db_edit                        (GlyrDatabase *db,
                                                         GlyrQuery *query,
                                                         GlyrMemCache *edited);
void                glyr_db_foreach                     (GlyrDatabase *db,
                                                         glyr_foreach_callback cb,
                                                         void *userptr);
GlyrDatabase *      glyr_db_init                        (const char *root_path);
void                glyr_db_insert                      (GlyrDatabase *db,
                                                         GlyrQuery *q,
                                                         GlyrMemCache *cache);
GlyrMemCache *      glyr_db_lookup                      (GlyrDatabase *db,
                                                         GlyrQuery *query);
GlyrMemCache *      glyr_db_make_dummy                  (void);
void                glyr_db_replace                     (GlyrDatabase *db,
                                                         unsigned char *md5sum,
                                                         GlyrQuery *query,
                                                         GlyrMemCache *data);
int                 (*glyr_foreach_callback)            (GlyrQuery *q,
                                                         GlyrMemCache *item,
                                                         void *userptr);

Description

The Cache offers application authors to store the items found by glyr persistently in a DB-Cache and get them again once needed. Before usage it is necessary to open the DB via glyr_db_init(), which expects a folder where the DB will be stored, after this there are 4 operations you can use on the query:

If you want to insert "own" caches, e.g. to indicate that some artist wasn't found you could use the following piece of code:

        // Create a new "dummy" cache
        GlyrMemCache * ct = glyr_db_make_dummy();

        // Query with filled in artist, album, title, type,
        // and opened db
        glyr_db_insert(db,&q,ct);

        glyr_cache_free(ct);

Details

GLYR_DB_FILENAME

#define GLYR_DB_FILENAME "metadata.db"

glyr_db_delete ()

int                 glyr_db_delete                      (GlyrDatabase *db,
                                                         GlyrQuery *query);

The database is searched for the artist, album, title and type specified in query. If items in the DB match they will deleted.

Other query-fields honored by glyr_db_delete():

db :

The Database

query :

Define what item shall be deleted.

Returns :

The number of deleted items.

glyr_db_destroy ()

void                glyr_db_destroy                     (GlyrDatabase *db_object);

Close the connection and free all associated memory. You may not use it anymore.

db_object :

A database connection

glyr_db_edit ()

int                 glyr_db_edit                        (GlyrDatabase *db,
                                                         GlyrQuery *query,
                                                         GlyrMemCache *edited);

A simple convenience function to delete caches according to the settings specified in query, (Same rules as in glyr_db_delete() apply here). After deleting the cache edited in inserted. If edited is a doubly linked list (next pointer is not NULL), then all items in the list are inserted.

You could have written it yourself like this:

int glyr_db_edit(GlyrDatabase * db, GlyrQuery * query, GlyrMemCache * edited)
{
  int result = 0;
  if(db && query)
  {
      result = glyr_db_delete(db,query);
      if(result != 0)
      {
          for(GlyrMemCache * elem = edited; elem; elem = elem->next)
          {
              glyr_db_insert(db,query,edited);
          }
      }
  }
  return result;
}

db :

The Database

query :

The query with set artist,album, type etc.

edited :

The edited cache.

Returns :

The number of replaced caches

glyr_db_foreach ()

void                glyr_db_foreach                     (GlyrDatabase *db,
                                                         glyr_foreach_callback cb,
                                                         void *userptr);

Iterate over all items in the database. Callback may not be null. If callback returns a number != 0, iteration aborts.

Callback parameters:

1) The artist / album / title / type that was used to get this cache is stored in 'query', other fields are not filled.

2) The actual cache completely filled.

3) The userpointer you passed as 3rd argument to glyr_db_foreach()

This is useful if you want to have statistics or such.

db :

A database connection

cb :

The callback to call on each item.

userptr :

A pointer to pass as second argument to the callback.

glyr_db_init ()

GlyrDatabase *      glyr_db_init                        (const char *root_path);

Allocates a new database object, and create a SQLite database at the given path. The filename is in GLYR_DB_FILENAME You can now use insert,delete, edit and lookup on it.

root_path :

Folder to create DB in

Returns :

A newly allocated GlyrDatabase, free with glyr_db_destroy

glyr_db_insert ()

void                glyr_db_insert                      (GlyrDatabase *db,
                                                         GlyrQuery *q,
                                                         GlyrMemCache *cache);

The cache wil be inserted to the db db, q is used to determine the artist, album, title and type.

db :

A database connection

q :

The query that was used to retrieve the cache

cache :

The cache to insert.

glyr_db_lookup ()

GlyrMemCache *      glyr_db_lookup                      (GlyrDatabase *db,
                                                         GlyrQuery *query);

The artist,album,title and type field are used to query the database.

If you used glyr_opt_lookup_db() to bind the DB to a query, You may use glyr_get() as an alternative for this method. If your specify "local" in glyr_opt_from() only the DB is searched.

Other query-fields honored by glyr_db_lookup():

db :

A database connection

query :

Define what to search for

Returns :

A newly allocated GlyrMemCache or NULL if nothing found

glyr_db_make_dummy ()

GlyrMemCache *      glyr_db_make_dummy                  (void);

The idea behind this function is to create a dummy entry for the cache, e.g. to indicate a certain item was not found. In this case you create a dummy with a 'rating' of -1 and push it into the DB. If one does a lookup (via glyr_get() or glyr_db_lookup()) then this cache will be returned, one is able to check if the item was not found before.

Returns :

A newly allocated cache, use glyr_cache_free() to free it.

glyr_db_replace ()

void                glyr_db_replace                     (GlyrDatabase *db,
                                                         unsigned char *md5sum,
                                                         GlyrQuery *query,
                                                         GlyrMemCache *data);

Simple convenience function to edit caches in the Database. Best understood by example:

// If you have a cache called 'c', that's already
// In the Database:
// Save the old checksum, edit it, update the database.
unsigned char old_md5sum[16] = {0};
memcpy(old_md5sum,c->md5sum,16);
glyr_cache_set_data(c,g_strdup("Changed the data - muahahah"),-1);
c->rating = 4200;
glyr_db_replace(s->local_db, old_md5sum, s, c);

Some caveats:

  • You may insert a cache several times, if the source url (cache->dsrc) is different, but with the same checksum. If you call glyr_db_replace() once more, the caches with the double md5sum get deleted and replaced by the new one.

db :

The Database

md5sum :

The md5sum of the cache you want to edit.

query :

The query with set artist,album, type etc.

data :

The edited cache.

glyr_foreach_callback ()

int                 (*glyr_foreach_callback)            (GlyrQuery *q,
                                                         GlyrMemCache *item,
                                                         void *userptr);