## GstUriHandler GstUriHandler — Interface to ease URI handling in plugins. |

## Synopsis

    #include <gst/gst.h>

                        GstURIHandler;
                        GstURIHandlerInterface;
    enum                GstURIType;
    #define             GST_URI_TYPE_IS_VALID               (type)
    gboolean            gst_uri_protocol_is_valid           (const gchar *protocol);
    gboolean            gst_uri_protocol_is_supported       (const GstURIType type,
                                                             const gchar *protocol);
    gboolean            gst_uri_is_valid                    (const gchar *uri);
    gboolean            gst_uri_has_protocol                (const gchar *uri,
                                                             const gchar *protocol);
    gchar*              gst_uri_get_protocol                (const gchar *uri);
    gchar*              gst_uri_get_location                (const gchar *uri);
    gchar*              gst_uri_construct                   (const gchar *protocol,
                                                             const gchar *location);
    GstElement*         gst_element_make_from_uri           (const GstURIType type,
                                                             const gchar *uri,
                                                             const gchar *elementname);
    guint               gst_uri_handler_get_uri_type        (GstURIHandler *handler);
    gchar**             gst_uri_handler_get_protocols       (GstURIHandler *handler);
    gchar*              gst_uri_handler_get_uri             (GstURIHandler *handler);
    gboolean            gst_uri_handler_set_uri             (GstURIHandler *handler,
                                                             const gchar *uri);
    void                gst_uri_handler_new_uri             (GstURIHandler *handler,
                                                             const gchar *uri);

## Object Hierarchy

      GInterface
       +----GstURIHandler

## Signals

      "new-uri"                                        : Run Last

## Description

The URIHandler is an interface that is implemented by Source and Sink GstElement to simplify then handling of URI.

An application can use the following functions to quickly get an element that handles the given URI for reading or writing (`gst_element_make_from_uri()`).

Source and Sink plugins should implement this interface when possible.

Last reviewed on 2005-11-09 (0.9.4)

## Details

### GstURIHandler

    typedef struct _GstURIHandler GstURIHandler;

Opaque GstURIHandler structure.

### GstURIHandlerInterface

    typedef struct {
      GTypeInterface	parent;

      /* querying capabilities */
      GstURIType		(* get_type)		(void);
      gchar **		(* get_protocols)	(void);

      /* using the interface */
      G_CONST_RETURN gchar *(* get_uri)		(GstURIHandler * handler);
      gboolean		(* set_uri)		(GstURIHandler * handler,
    						 const gchar *	 uri);

      GstURIType		(* get_type_full)	(GType type);
      gchar **		(* get_protocols_full)	(GType type);
    } GstURIHandlerInterface;

GstElements using this interface should implement these methods.

GTypeInterface `parent`; | The parent interface type
`get_type` () | Method to tell whether the element handles source or sink URI.
`get_protocols` () | Method to return the list of protocols handled by the element.
`get_uri` () | Method to return the URI currently handled by the element.
`set_uri` () | Method to set a new URI.
`get_type_full` () | Variant of get_type which takes a GType argument. This is for use by bindings that need to pass context when creating a URI Handler. * If implemented, get_type will be used in preference to get_type_full. Since: 0.10.15
`get_protocols_full` () | Variant of get_type which takes a GType argument. This is for use by bindings that need to pass context when creating a URI Handler. If implemented, get_protocols will be used in preference to get_protocols_full. Since: 0.10.15

### enum GstURIType

    typedef enum {
      GST_URI_UNKNOWN,
      GST_URI_SINK,
      GST_URI_SRC
    } GstURIType;

The different types of URI direction.

`GST_URI_UNKNOWN` | The URI direction is unknown
`GST_URI_SINK` | The URI is a consumer.
`GST_URI_SRC` | The URI is a producer.

### GST_URI_TYPE_IS_VALID()

    #define GST_URI_TYPE_IS_VALID(type) ((type) == GST_URI_SRC || (type) == GST_URI_SINK)

Tests if the type direction is valid.

`type` : | A GstURIType

### gst_uri_protocol_is_valid ()

    gboolean            gst_uri_protocol_is_valid           (const gchar *protocol);

Tests if the given string is a valid protocol identifier. Protocols must consist of alphanumeric characters and not start with a number.

`protocol` : | A string
Returns : | TRUE if the string is a valid protocol identifier, FALSE otherwise.

### gst_uri_protocol_is_supported ()

    gboolean            gst_uri_protocol_is_supported       (const GstURIType type,
                                                             const gchar *protocol);

Checks if an element exists that supports the given URI protocol. Note that a positive return value does not imply that a subsequent call to `gst_element_make_from_uri()` is guaranteed to work.

`type` : | Whether to check for a source or a sink
`protocol` : | Protocol that should be checked for (e.g. "http" or "smb")
Returns : | TRUE

Since 0.10.13

### gst_uri_is_valid ()

    gboolean            gst_uri_is_valid                    (const gchar *uri);

Tests if the given string is a valid URI identifier. URIs start with a valid protocol followed by "://" and maybe a string identifying the location.

`uri` : | A URI string
Returns : | TRUE if the string is a valid URI

### gst_uri_has_protocol ()

    gboolean            gst_uri_has_protocol                (const gchar *uri,
                                                             const gchar *protocol);

Checks if the protocol of a given valid URI matches `protocol`.

`uri` : | an URI string
`protocol` : | a protocol string (e.g. "http")
Returns : | `TRUE` if the protocol matches.

Since 0.10.4

### gst_uri_get_protocol ()

    gchar*              gst_uri_get_protocol                (const gchar *uri);

Extracts the protocol out of a given valid URI. The returned string must be freed using `g_free()`.

`uri` : | A URI string
Returns : | The protocol for this URI.

### gst_uri_get_location ()

    gchar*              gst_uri_get_location                (const gchar *uri);

Extracts the location out of a given valid URI, ie. the protocol and "://" are stripped from the URI, which means that the location returned includes the hostname if one is specified. The returned string must be freed using `g_free()`.

`uri` : | A URI string
Returns : | The location for this URI. Returns NULL if the URI isn't valid. If the URI does not contain a location, an empty string is returned.

### gst_uri_construct ()

    gchar*              gst_uri_construct                   (const gchar *protocol,
                                                             const gchar *location);

Constructs a URI for a given valid protocol and location.

`protocol` : | Protocol for URI
`location` : | Location for URI
Returns : | a new string for this URI. Returns NULL if the given URI protocol is not valid, or the given location is NULL.

### gst_element_make_from_uri ()

    GstElement*         gst_element_make_from_uri           (const GstURIType type,
                                                             const gchar *uri,
                                                             const gchar *elementname);

Creates an element for handling the given URI.

`type` : | Whether to create a source or a sink
`uri` : | URI to create an element for
`elementname` : | Name of created element, can be NULL.
Returns : | a new element or NULL if none could be created

### gst_uri_handler_get_uri_type ()

    guint               gst_uri_handler_get_uri_type        (GstURIHandler *handler);

Gets the type of the given URI handler

Returns: the GstURIType of the URI handler.

`handler` : | A GstURIHandler.
Returns : | GST_URI_UNKNOWN if the `handler` isn't implemented correctly.

### gst_uri_handler_get_protocols ()

    gchar**             gst_uri_handler_get_protocols       (GstURIHandler *handler);

Gets the list of protocols supported by `handler`. This list may not be modified.

Returns: the supported protocols.

`handler` : | A GstURIHandler.
Returns : | NULL if the `handler` isn't implemented properly, or the `handler` doesn't support any protocols.

### gst_uri_handler_get_uri ()

    gchar*              gst_uri_handler_get_uri             (GstURIHandler *handler);

Gets the currently handled URI.

Returns: the URI currently handled by the `handler`.

`handler` : | A GstURIHandler
Returns : | NULL if there are no URI currently handled. The returned string must not be modified or freed.

### gst_uri_handler_set_uri ()

    gboolean            gst_uri_handler_set_uri             (GstURIHandler *handler,
                                                             const gchar *uri);

Tries to set the URI of the given handler.

`handler` : | A GstURIHandler
`uri` : | URI to set
Returns : | TRUE if the URI was set successfully, else FALSE.

### gst_uri_handler_new_uri ()

    void                gst_uri_handler_new_uri             (GstURIHandler *handler,
                                                             const gchar *uri);

Emits the new-uri signal for a given handler, when that handler has a new URI. This function should only be called by URI handlers themselves.

`handler` : | A GstURIHandler
`uri` : | new URI or NULL if it was unset

## Signal Details

### The "new-uri" signal

    void                user_function                      (GstURIHandler *handler,
                                                            gchar         *uri,
                                                            gpointer       user_data)      : Run Last

The URI of the given `handler` has changed.

`handler` : | The GstURIHandler which emitted the signal
`uri` : | The new URI, or NULL if the URI was removed
`user_data` : | user data set when the signal handler was connected.