GUPnPDLNADiscoverer

## GUPnPDLNADiscoverer GUPnPDLNADiscoverer — Utility API for discovering DLNA profile/mime type and other metadata for given media. |

## Synopsis

                        GUPnPDLNADiscoverer;
    GUPnPDLNADiscoverer * gupnp_dlna_discoverer_new         (GstClockTime timeout,
                                                             gboolean relaxed_mode,
                                                             gboolean extended_mode);
    #define             gupnp_dlna_discoverer_start         (discoverer)
    #define             gupnp_dlna_discoverer_stop          (discoverer)
    gboolean            gupnp_dlna_discoverer_discover_uri  (GUPnPDLNADiscoverer *discoverer,
                                                             const gchar *uri);
    GUPnPDLNAInformation * gupnp_dlna_discoverer_discover_uri_sync
                                                            (GUPnPDLNADiscoverer *discoverer,
                                                             const gchar *uri,
                                                             GError **err);
    GUPnPDLNAProfile *  gupnp_dlna_discoverer_get_profile   (GUPnPDLNADiscoverer *self,
                                                             const gchar *name);
    const GList *       gupnp_dlna_discoverer_list_profiles (GUPnPDLNADiscoverer *self);
    gboolean            gupnp_dlna_discoverer_get_relaxed_mode
                                                            (GUPnPDLNADiscoverer *self);
    gboolean            gupnp_dlna_discoverer_get_extended_mode
                                                            (GUPnPDLNADiscoverer *self);

## Object Hierarchy

      GObject
       +----GstDiscoverer
             +----GUPnPDLNADiscoverer

## Properties

      "extended-mode"            gboolean              : Read / Write / Construct Only
      "relaxed-mode"             gboolean              : Read / Write / Construct Only

## Signals

      "done"                                           : Run Last

## Description

The GUPnPDLNADiscoverer object provides a light-weight wrapper over the GstDiscoverer API. The latter provides a simple interface to discover media metadata given a URI. GUPnPDLNADiscoverer extends this API to also provide a DLNA profile name and mime type for the media.

The API provided corresponds very closely to the API provided by GstDiscoverer - both synchronous and asynchronous discovery of metadata are possible.

The asynchronous mode requires a running GMainLoop in the default GMainContext, where one connects to the various signals, appends the URIs to be processed and then asks for the discovery to begin.

## Details

### GUPnPDLNADiscoverer

    typedef struct _GUPnPDLNADiscoverer GUPnPDLNADiscoverer;

The top-level object used to for metadata extraction.

### gupnp_dlna_discoverer_new ()

    GUPnPDLNADiscoverer * gupnp_dlna_discoverer_new         (GstClockTime timeout,
                                                             gboolean relaxed_mode,
                                                             gboolean extended_mode);

Creates a new GUPnPDLNADiscoverer object with the given default timeout value.

`timeout` : | default discovery timeout, in nanoseconds
`relaxed_mode` : | set to TRUE, to enable relaxed mode support. FALSE otherwise
`extended_mode` : | set to TRUE, to enable extended mode support. FALSE otherwise
Returns : | A new GUPnPDLNADiscoverer object.

### gupnp_dlna_discoverer_start()

    #define             gupnp_dlna_discoverer_start(discoverer)

Allows asynchronous discovery of URIs to begin.

`discoverer` : | GUPnPDLNADiscoverer object to start discovery on

### gupnp_dlna_discoverer_stop()

    #define             gupnp_dlna_discoverer_stop(discoverer)

Stops asynchronous discovery of URIs.

`discoverer` : | GUPnPDLNADiscoverer object to stop discovery on

### gupnp_dlna_discoverer_discover_uri ()

    gboolean            gupnp_dlna_discoverer_discover_uri  (GUPnPDLNADiscoverer *discoverer,
                                                             const gchar *uri);

Queues `uri` for metadata discovery. When discovery is completed, the "discovered" signal is emitted on `discoverer`.

`discoverer` : | GUPnPDLNADiscoverer object to use for discovery
`uri` : | URI to gather metadata for
Returns : | TRUE if `uri` was successfully queued, FALSE otherwise.

### gupnp_dlna_discoverer_discover_uri_sync ()

    GUPnPDLNAInformation * gupnp_dlna_discoverer_discover_uri_sync
                                                            (GUPnPDLNADiscoverer *discoverer,
                                                             const gchar *uri,
                                                             GError **err);

Synchronously gathers metadata for `uri`.

`discoverer` : | GUPnPDLNADiscoverer object to use for discovery
`uri` : | URI to gather metadata for
`err` : | contains details of the error if discovery fails, else is NULL
Returns : | a GUPnPDLNAInformation with the metadata for `uri` on success, NULL otherwise. [transfer full]

### gupnp_dlna_discoverer_get_profile ()

    GUPnPDLNAProfile *  gupnp_dlna_discoverer_get_profile   (GUPnPDLNADiscoverer *self,
                                                             const gchar *name);

Given `name`, this finds the corresponding DLNA profile information (stored as a GUPnPDLNAProfile).

`self` : | The GUPnPDLNADiscoverer object
`name` : | The name of the DLNA profile to be retrieved
Returns : | a GUPnPDLNAProfile on success, NULL otherwise. [transfer full]

### gupnp_dlna_discoverer_list_profiles ()

    const GList *       gupnp_dlna_discoverer_list_profiles (GUPnPDLNADiscoverer *self);

Retuns a list of the all the DLNA profiles supported by `self`.

`self` : | The GUPnPDLNADiscoverer whose profile list is required
Returns : | a GList of GUPnPDLNAProfile on success, NULL otherwise. [transfer none][element-type GUPnPDLNAProfile]

### gupnp_dlna_discoverer_get_relaxed_mode ()

    gboolean            gupnp_dlna_discoverer_get_relaxed_mode
                                                            (GUPnPDLNADiscoverer *self);

`self` : | The GUPnPDLNADiscoverer object
Returns : | true if relaxed mode is set and false otherwise

### gupnp_dlna_discoverer_get_extended_mode ()

    gboolean            gupnp_dlna_discoverer_get_extended_mode
                                                            (GUPnPDLNADiscoverer *self);

`self` : | The GUPnPDLNADiscoverer object
Returns : | true if application is using extended mode and false otherwise

## Property Details

### The `"extended-mode"` property

      "extended-mode"            gboolean              : Read / Write / Construct Only

Indicates support for profiles that are not part of the DLNA specification.

Default value: FALSE

### The `"relaxed-mode"` property

      "relaxed-mode"             gboolean              : Read / Write / Construct Only

Indicates that profile matching shouldbe strictly compliant with the DLNA specification.

Default value: FALSE

## Signal Details

### The `"done"` signal

    void                user_function                      (GUPnPDLNADiscoverer  *discoverer,
                                                            GUPnPDLNAInformation *dlna,
                                                            GError               *err,
                                                            gpointer              user_data)       : Run Last

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

The reciever must unref `dlna` with when done using it.

`discoverer` : | the GUPnPDLNADiscoverer
`dlna` : | the results as GUPnPDLNAInformation
`err` : | contains details of the error if discovery fails, else is NULL
`user_data` : | user data set when the signal handler was connected.