DmapDb: libdmapsharing Reference Manual

## DmapDb DmapDb — An interface for DMAP databases. |

## Functions

void | (*DmapIdRecordFunc) ()
guint | dmap_db_add ()
guint | dmap_db_add_with_id ()
guint | dmap_db_add_path ()
DmapRecord * | dmap_db_lookup_by_id ()
guint | dmap_db_lookup_id_by_location ()
void | dmap_db_foreach ()
gulong | dmap_db_count ()
GHashTable * | dmap_db_apply_filter ()

## Types and Values

enum | DmapDbId

## Object Hierarchy

        GEnum
        ╰── DmapDbId
        GInterface
        ╰── DmapDb

## Description

DmapDb provides an interface for DMAP databases.

## Functions

### DmapIdRecordFunc ()

    void
    (*DmapIdRecordFunc) (guint id,
                         DmapRecord *record,
                         gpointer user_data);

The type of function passed to `dmap_db_foreach()`.

#### Parameters

id | a DMAP record ID |
record | a DmapRecord |
user_data | user data. | [closure]

### dmap_db_add ()

    guint
    dmap_db_add (DmapDb *db,
                 DmapRecord *record,
                 GError **error);

Add a record to the database.

#### Parameters

db | A media database. |
record | A database record. |
error | return location for a GError, or NULL. |

#### Returns

The ID for the newly added record or `DMAP_DB_ID_BAD` on failure. A reference to the record will be retained by the database (if required; an adapter-type implementation might not want to retain a reference as the record data may be placed elsewhere). In all cases, a returned record should be unrefed by the calling code.

### dmap_db_add_with_id ()

    guint
    dmap_db_add_with_id (DmapDb *db,
                         DmapRecord *record,
                         guint id,
                         GError **error);

Add a record to the database and assign it the given ID. `id` cannot be `DMAP_DB_ID_BAD` .

#### Parameters

db | A media database. |
record | A database record. |
id | A database record ID. |
error | return location for a GError, or NULL. |

#### Returns

The ID for the newly added record or DMAP_DB_ID_BAD on failure.

See also the notes for dmap_db_add regarding reference counting.

### dmap_db_add_path ()

    guint
    dmap_db_add_path (DmapDb *db,
                      const gchar *path,
                      GError **error);

Create a record and add it to the database.

#### Parameters

db | A media database. |
path | A path to an appropriate media file. |
error | return location for a GError, or NULL. |

#### Returns

The ID for the newly added record or DMAP_DB_ID_BAD on failure.

See also the notes for dmap_db_add regarding reference counting.

### dmap_db_lookup_by_id ()

    DmapRecord *
    dmap_db_lookup_by_id (const DmapDb *db,
                          guint id);

#### Parameters

db | A media database. |
id | A record ID. |

#### Returns

the database record corresponding to `id` . `id` cannot be DMAP_DB_ID_BAD. The returned record should be unrefed by the calling code when no longer required.

If you are implementing a full database using this API, then you probably want to increment the reference count before returning a record pointer.

On the other hand, if you are implementing an adapter class and the records are stored elsewhere, then you will probably return a transient record. That is, once the user is done using it, the returned record should be free'd because it is a adapter copy of the real record. In this case, the reference count should not be incremented before returning a record pointer.

[transfer full]

### dmap_db_lookup_id_by_location ()

    guint
    dmap_db_lookup_id_by_location (const DmapDb *db,
                                   const gchar *location);

#### Parameters

db | A media database. |
location | A record location. |

#### Returns

the database id for the record corresponding to `path` or DMAP_DB_ID_BAD if such a record does not exist.

### dmap_db_foreach ()

    void
    dmap_db_foreach (const DmapDb *db,
                     DmapIdRecordFunc func,
                     gpointer data);

Apply a function to each record in a media database.

#### Parameters

db | A media database. |
func | The function to apply to each record in the database. | [scope call]
data | User data to pass to the function. |

### dmap_db_count ()

    gulong
    dmap_db_count (const DmapDb *db);

#### Parameters

db | A media database. |

#### Returns

the number of records in the database.

### dmap_db_apply_filter ()

    GHashTable *
    dmap_db_apply_filter (DmapDb *db,
                          GSList *filter_def);

#### Parameters

db | A media database. |
filter_def | A series of filter definitions. | [element-type DmapDbFilterDefinition]

#### Returns

the records which satisfy a record in `filter_def` .

[element-type guint DmapRecord][transfer full]

## Types and Values

### enum DmapDbId

Special DmapDb ID values.

#### Members

DMAP_DB_ID_BAD | the value which represents a bad DmapDb ID. |