GUPnPDLNAMetadataExtractor

## GUPnPDLNAMetadataExtractor GUPnPDLNAMetadataExtractor — Base class for extracting metadata for given media. |

## Synopsis

                        GUPnPDLNAMetadataExtractor;
                        GUPnPDLNAMetadataExtractorClass;
    gboolean            gupnp_dlna_metadata_extractor_extract_async
                                                            (GUPnPDLNAMetadataExtractor *extractor,
                                                             const gchar *uri,
                                                             guint timeout_in_ms,
                                                             GError **error);
    GUPnPDLNAInformation * gupnp_dlna_metadata_extractor_extract_sync
                                                            (GUPnPDLNAMetadataExtractor *extractor,
                                                             const gchar *uri,
                                                             guint timeout_in_ms,
                                                             GError **error);
    void                gupnp_dlna_metadata_extractor_emit_done
                                                            (GUPnPDLNAMetadataExtractor *extractor,
                                                             GUPnPDLNAInformation *info,
                                                             GError *error);

## Object Hierarchy

      GObject
       +----GUPnPDLNAMetadataExtractor

## Signals

      "done"                                           : Run Last

## Description

GUPnPDLNAMetadataExtractor is used by GUPnPDLNAProfileGuesser to get needed metadata for profile matching. This class itself does not implement any metadata extraction features. For that it is expected to provide a plugin which:

- Provides a GUPnPDLNAMetadataExtractor subclass implementation.

- Exports a `gupnp_dlna_get_default_extractor`() which takes no parameters and returns a GUPnPDLNAMetadataExtractor.

GModule is used for loading the plugin, so GModule's features can be used also (like exporting `g_module_check_init`() to initialize the multimedia framework used for extracting metadata).

Default plugin directory and default plugin file is set during configuration stage, but it can be overriden during runtime by setting respectively `GUPNP_DLNA_METADATA_BACKEND` and `GUPNP_DLNA_METADATA_BACKEND_DIR` environment variables before the plugin is loaded (i.e. before GUPnPDLNAProfileGuesser is used for guessing profile).

The `GUPNP_DLNA_METADATA_BACKEND` environment variable should hold a name like `"gstreamer"`, so `libgstreamer.so` will be loaded. For determining a plugin filename `g_module_build_path()` is used.

If subclassing GUPnPDLNAMetadataExtractor then also GUPnPDLNAInformation, GUPnPDLNAAudioInformation, GUPnPDLNAContainerInformation, GUPnPDLNAImageInformation and GUPnPDLNAVideoInformation have to be subclassed as well.

## Details

### GUPnPDLNAMetadataExtractor

    typedef struct _GUPnPDLNAMetadataExtractor GUPnPDLNAMetadataExtractor;

The top-level object used to for metadata extraction.

### GUPnPDLNAMetadataExtractorClass

    typedef struct {
            GObjectClass parent_class;

            /* virtuals */
            gboolean
            (* extract_async) (GUPnPDLNAMetadataExtractor  *extractor,
                               const gchar                 *uri,
                               guint                        timeout_in_ms,
                               GError                     **error);

            GUPnPDLNAInformation *
            (* extract_sync) (GUPnPDLNAMetadataExtractor  *extractor,
                              const gchar                 *uri,
                              guint                        timeout_in_ms,
                              GError                     **error);

            gpointer _reserved[12];
    } GUPnPDLNAMetadataExtractorClass;

GObjectClass `parent_class`; | Parent class.
`extract_async` () | This is called by GUPnPDLNAProfileGuesser to get a information about media file asynchronously.
`extract_sync` () | This is called by GUPnPDLNAProfileGuesser to get a information about media file synchronously.
gpointer `_reserved`[12]; | Padding. Ignore it.

### gupnp_dlna_metadata_extractor_extract_async ()

    gboolean            gupnp_dlna_metadata_extractor_extract_async
                                                            (GUPnPDLNAMetadataExtractor *extractor,
                                                             const gchar *uri,
                                                             guint timeout_in_ms,
                                                             GError **error);

Queues `uri` for metadata discovery. When discovery is completed, the ::done signal is emitted on `extractor`.

`extractor` : | GUPnPDLNAMetadataExtractor object to use for discovery
`uri` : | URI to gather metadata for
`timeout_in_ms` : | Timeout in miliseconds.
`error` : | A GError.
Returns : | `TRUE` if `uri` was successfully queued, `FALSE` otherwise.

### gupnp_dlna_metadata_extractor_extract_sync ()

    GUPnPDLNAInformation * gupnp_dlna_metadata_extractor_extract_sync
                                                            (GUPnPDLNAMetadataExtractor *extractor,
                                                             const gchar *uri,
                                                             guint timeout_in_ms,
                                                             GError **error);

Discovers synchronously metadata of given `uri`.

`extractor` : | GUPnPDLNAMetadataExtractor object to use for discovery
`uri` : | URI to gather metadata for
`timeout_in_ms` : | Timeout in miliseconds.
`error` : | A GError.
Returns : | A GUPnPDLNAInformation object if discovery succeeded, otherwise `NULL`.

### gupnp_dlna_metadata_extractor_emit_done ()

    void                gupnp_dlna_metadata_extractor_emit_done
                                                            (GUPnPDLNAMetadataExtractor *extractor,
                                                             GUPnPDLNAInformation *info,
                                                             GError *error);

Emits ::done signal. This function is intended to be used by subclasses of GUPnPDLNAMetadataExtractor. It is required to always pass a meaningful `info`, even in case of error. That way a receiver of this signal can know which URI discovery failed by using `gupnp_dlna_information_get_uri()`.

`extractor` : | A GUPnPDLNAMetadataExtractor object.
`info` : | A GUPnPDLNAInformation about discovered URI. [transfer none]
`error` : | A GError. [allow-none][transfer none]

## Signal Details

### The `"done"` signal

    void                user_function                      (GUPnPDLNAMetadataExtractor *extractor,
                                                            GUPnPDLNAInformation       *info,
                                                            GError                     *error,
                                                            gpointer                    user_data)      : Run Last

Will be emitted when all information on a URI could be discovered.

`extractor` : | The GUPnPDLNAMetadataExtractor.
`info` : | The results as GUPnPDLNAInformation. [transfer none]
`error` : | Contains details of the error if discovery fails, otherwise is `NULL`. [allow-none][transfer none]
`user_data` : | user data set when the signal handler was connected.