## How to use libtracker-extract

How to use libtracker-extract — The essentials by example

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <libtracker-extract/tracker-extract.h>

    gboolean            tracker_extract_get_metadata        (TrackerExtractInfo *info);

## Description

The libtracker-extract library is the foundation for Tracker metadata extraction of embedded data in files.

Tracker comes with extractors written for the most common file types (like MP3, JPEG, PNG, etc.), however, for more special cases, 3rd party applications may want to write their own plugin to extract their own file formats. This documentation describes how to do that.

Example 1. Basic extractor example

An example of how to write an extractor to retrieve PNG embedded metadata.

     G_MODULE_EXPORT gboolean
     tracker_extract_get_metadata (TrackerExtractInfo *info)
     {
             GFile *file;
             TrackerSparqlBuilder *metadata;
             gint height, width;

             file = tracker_extract_info_get_file (info);
             metadata = tracker_extract_info_get_metadata_builder (info);

             /* Do data extraction. */
             height = ...
             width = ...

             /* Insert data into TrackerSparqlBuilder object. */
             tracker_sparql_builder_predicate (metadata, "a");
             tracker_sparql_builder_object (metadata, "nfo:Image");
             tracker_sparql_builder_object (metadata, "nmm:Photo");

             tracker_sparql_builder_predicate (metadata, "nfo:width");
             tracker_sparql_builder_object_int64 (metadata, width);

             tracker_sparql_builder_predicate (metadata, "nfo:height");
             tracker_sparql_builder_object_int64 (metadata, height);

             /* Were we successful or not? */
             return TRUE;
     }

NOTE: This example has changed subtly since 0.10. For details see `tracker_extract_get_metadata()`.

## Details

### tracker_extract_get_metadata ()

    gboolean            tracker_extract_get_metadata        (TrackerExtractInfo *info);

This function must be provided by ALL extractors. This is merely the declaration of the function which must be written by each extractor.

This is checked by tracker-extract by looking up the symbols for each started plugin and making sure this function exists.

The `info` parameter contains required information for the extraction and a location to store the results. The `tracker_extract_info_get_metadata_builder()` function returns a TrackerSparqlBuilder constructed through `tracker_sparql_builder_new_embedded_insert()`. The subject is already set to be the file URN, so implementations of this function should just provide predicate/object(s) pairs. The triples contained in this object at the end of the function will be merged with further file information from miners.

Whenever any of the inserted triples rely on entities that should also be provided by this extractor (for example, album or artist information from a song), such insertions should be added to the preupdate object returned by `tracker_extract_info_get_preupdate_builder()`. This is a TrackerSparqlBuilder created through `tracker_sparql_builder_new_update()`.

NOTE: If upgrading from 0.10, this function replaces the old function named `tracker_extract_get_data()` and has a few subtle differences. First, there is a return value for success and the parameters are contained in `info` instead of being passed individually. Second, the extractor is passed the detected MIME type of the file being extracted.

`info` : | a TrackerExtractInfo object
Returns : | `TRUE` if the extraction succeeded, `FALSE` otherwise.

Since 0.12