## GstUriHandler

GstUriHandler — Plugin feature that handles URI types

## Synopsis

    struct      GstURIHandler;
    #define     GST_TYPE_URI_HANDLER
    #define     GST_URI_TYPE_IS_VALID           (type)
    gboolean    gst_uri_protocol_is_valid       (const gchar *protocol);
    gboolean    gst_uri_is_valid                (const gchar *uri);
    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);
    G_CONST_RETURN 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

## Known Implementations

GstURIHandler is implemented by GstFileSrc, GstMultiFileSink and GstFileSink.

## Description

The URIHandler is a pluginfeature that can be used to locate element and the element property that can handle a given URI.

## Details

### struct GstURIHandler

    struct GstURIHandler;

### GST_TYPE_URI_HANDLER

    #define GST_TYPE_URI_HANDLER		(gst_uri_handler_get_type ())

### GST_URI_TYPE_IS_VALID()

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

`type` : |

### 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` : | string to check
Returns : | TRUE if the string is a valid protocol identifier

### 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 a string identifying the location.

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

### 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` : | URI to get protocol from
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. So the protocol and "://" are stripped from the URI. The returned string must be freed using `g_free()`.

`uri` : | URI to get the location from
Returns : | The location for this URI.

### 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

### 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` : | wether to create a source or a sink
`uri` : | URI to create element for
`elementname` : | optional name of created element
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 a URI handler

`handler` : | Handler to query type of
Returns : | the type of the URI handler

### gst_uri_handler_get_protocols ()

    gchar**     gst_uri_handler_get_protocols   (GstURIHandler *handler);

Gets the list of supported protocols for this handler. This list may not be modified.

`handler` : | Handler to get protocols for
Returns : | the supported protocols

### gst_uri_handler_get_uri ()

    G_CONST_RETURN gchar* gst_uri_handler_get_uri
                                                (GstURIHandler *handler);

Gets the currently handled URI of the handler or NULL, if none is set.

`handler` : | handler to query URI of
Returns : | the URI

### 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 and returns TRUE if it succeeded.

`handler` : | handler to set URI of
`uri` : | URI to set
Returns : | TRUE, if the URI was set successfully

### gst_uri_handler_new_uri ()

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

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

`handler` : | handler with a new URI
`uri` : | new URI or NULL if it was unset