Browsing the contents of a source

The major use case of a source is browsing. Developers can explore the contents of a particular container exposed by the source using the method mafw_source_browse and the object identifier of the container. Here is an example that browses contents from the root container of a certain source:


static void
browse_cb(MafwSource *source,
          guint browseid,
          gint remaining,
          guint index,
          const gchar *objectid,
          GHashTable *metadata,
          gpointer user_data,
          const GError *error)
{
        if (error != NULL) {
                g_print("Browse error %d: %s\n", error->code, error->message);
        } else if (objectid != NULL) {
                gchar *title, *artist, *album, *mime;

                if (metadata) {
                        GValue *v;
                        v = mafw_metadata_first(metadata,
                                                MAFW_METADATA_KEY_TITLE);
                        title = v ? g_value_get_string(v) : "Unknown";
                        v = mafw_metadata_first(metadata,
                                                MAFW_METADATA_KEY_ARTIST);
                        artist = v ? g_value_get_string(v) : "Unknown";
                        v = mafw_metadata_first(metadata,
                                                MAFW_METADATA_KEY_ALBUM);
                        album = v ? g_value_get_string(v) : "Unknown";
                        v = mafw_metadata_first(metadata,
                                                MAFW_METADATA_KEY_MIME);
                        mime = v ? g_value_get_string(v) : "Unknown";
                } else {
                        title = "Unknown";
                        artist = "Unknown";
                        album = "Unknown";
                        mime = "Unknown";
                }

                g_print("Got object ID: %s\n", objectid);
                g_print("        Index: %u\n", index);
                g_print("        Title: %s\n", title);
                g_print("       Artist: %s\n", artist);
                g_print("        Album: %s\n", album);
                g_print("         Mime: %s\n", mime);
        } else {
                g_print("The query %d did not return any results\n", browseid);
        }
}

static void
browse_example (MafwSource *source, gchar *objectid)
{
        const gchar *const *keys;
        guint browseid;

        keys = MAFW_SOURCE_LIST(
                MAFW_METADATA_KEY_MIME,
                MAFW_METADATA_KEY_ARTIST,
                MAFW_METADATA_KEY_ALBUM,
                MAFW_METADATA_KEY_TITLE);

        browseid =
                mafw_source_browse(
                   source,            /* The source object */
                   objectid,          /* The object ID to browse */
                   FALSE,             /* Do recursive browse? */
                   NULL,              /* Filter */
                   NULL,              /* Sort criteria */
                   keys,              /* Metadata to retrieve */
                   0, 20,             /* Offset and count */
                   browse_cb,         /* Callback */
                   NULL);             /* Callback user data */
}

The example browses the contents of a given object identifier in particular source. The meaning of the parameters is:

Source, the MafwSource instance to be browsed.
ObjectID, the object identifier of the container to be browsed.
Recursive, whether the container should be browsed recursively or not.
Filter, specifies an optional filter string in a syntax similar to that used in LDAP search filters.
Sort criteria, a string used to specify the criteria that should be followed to sort the browse results.
Keys, metadata keys we are interested in retrieving along with each object identifier returned with the browse operation.
Offset, the index of the first item to retrieve from the list of items that match the browse query.
Offset, the maximum number of elements to retrieve from the list of items that match the browse query, starting at the index specified by the Offset parameter.
Callback, this callback function is called whenever a matching result is found.
Callback user data, user data for the callback.

For more details, please check the Mafw API reference.

The mafw_source_browse function returns a browse identifier that can be used to match browse results with the corresponding browse operations.

The results of the browse call are returned using the provided callback. This callback is invoked each time a matching result is found by the source. Each time the callback is invoked it informs about:

Source, the MafwSource that is producing the result.
Browse ID, that allows the developer to match a result with a particular browse operation.
Remaining, which informs about the remaining items that have matched the browse query and are pending to be sent through the callback. When this value reaches 0 it means that all the results have been sent and the operations has finished.
Index, the index of the current item in the list of matched results.
Object ID, the object ID of the current item.
Metadata, the metadata values associated to the current item.
User Data, user data of the callback.
Error, a GError that, if set, informs of an error in the browse operation.

Also, in case that no results match the browse operation, the callback is invoked once, with the object ID parameter set to NULL.