## GstUriHandler

GstUriHandler — Interface to ease URI handling in plugins.

## Functions

GQuark | gst_uri_error_quark ()
#define | GST_URI_TYPE_IS_VALID()
gboolean | gst_uri_protocol_is_valid ()
gboolean | gst_uri_protocol_is_supported ()
gboolean | gst_uri_is_valid ()
gboolean | gst_uri_has_protocol ()
gchar * | gst_uri_get_protocol ()
gchar * | gst_uri_get_location ()
gchar * | gst_uri_construct ()
gchar * | gst_filename_to_uri ()
GstElement * | gst_element_make_from_uri ()
GstURIType | gst_uri_handler_get_uri_type ()
const gchar * const * | gst_uri_handler_get_protocols ()
gchar * | gst_uri_handler_get_uri ()
gboolean | gst_uri_handler_set_uri ()

## Types and Values

| GstURIHandler
struct | GstURIHandlerInterface
enum | GstURIType
enum | GstURIError
#define | GST_URI_NO_PORT

## Object Hierarchy

        GInterface
        ╰── GstURIHandler

## Includes

    #include <gst/gst.h>

## Description

The GstURIHandler is an interface that is implemented by Source and Sink GstElement to unify 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.

## Functions

### gst_uri_error_quark ()

    GQuark
    gst_uri_error_quark (void);

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

#### Parameters

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 '.' and must start with a alphabetic character. See RFC 3986 Section 3.1.

#### Parameters

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.

#### Parameters

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

#### Returns

`TRUE`

### 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 scheme followed by ":" and maybe a string identifying the location.

#### Parameters

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` .

#### Parameters

uri | a URI string |
protocol | a protocol string (e.g. "http") |

#### Returns

`TRUE` if the protocol matches.

### 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()`.

#### Parameters

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()`.

Free-function: g_free

#### Parameters

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.

[transfer full]

### gst_uri_construct ()

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

Constructs a URI for a given valid protocol and location.

Free-function: g_free

#### Parameters

protocol | Protocol for URI |
location | Location for URI. | [transfer none]

#### Returns

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

[transfer full]

### gst_filename_to_uri ()

    gchar *
    gst_filename_to_uri (const gchar *filename,
                         GError **error);

Similar to `g_filename_to_uri()`, but attempts to handle relative file paths as well. Before converting `filename` into an URI, it will be prefixed by the current working directory if it is a relative path, and then the path will be canonicalised so that it doesn't contain any './' or '../' segments.

On Windows filename should be in UTF-8 encoding.

#### Parameters

filename | absolute or relative file name path |
error | pointer to error, or `NULL` |

#### Returns

newly-allocated URI string, or NULL on error. The caller must free the URI string with `g_free()` when no longer needed.

### gst_element_make_from_uri ()

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

Creates an element for handling the given URI.

#### Parameters

type | Whether to create a source or a sink |
uri | URI to create an element for |
elementname | Name of created element, can be `NULL`. | [allow-none]
error | address where to store error information, or `NULL`. | [allow-none]

#### Returns

a new element or `NULL` if none could be created.

[transfer floating]

### gst_uri_handler_get_uri_type ()

    GstURIType
    gst_uri_handler_get_uri_type (GstURIHandler *handler);

Gets the type of the given URI handler

#### Parameters

handler | A GstURIHandler. |

#### Returns

the GstURIType of the URI handler. Returns GST_URI_UNKNOWN if the `handler` isn't implemented correctly.

### gst_uri_handler_get_protocols ()

    const gchar * const *
    gst_uri_handler_get_protocols (GstURIHandler *handler);

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

#### Parameters

handler | A GstURIHandler. |

#### Returns

the supported protocols. Returns `NULL` if the `handler` isn't implemented properly, or the `handler` doesn't support any protocols.

[transfer none][element-type utf8][nullable]

### gst_uri_handler_get_uri ()

    gchar *
    gst_uri_handler_get_uri (GstURIHandler *handler);

Gets the currently handled URI.

#### Parameters

handler | A GstURIHandler |

#### Returns

the URI currently handled by the `handler` . Returns `NULL` if there are no URI currently handled. The returned string must be freed with `g_free()` when no longer needed.

[transfer full][nullable]

### gst_uri_handler_set_uri ()

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

Tries to set the URI of the given handler.

#### Parameters

handler | A GstURIHandler |
uri | URI to set |
error | address where to store a GError in case of an error, or `NULL`. | [allow-none]

#### Returns

`TRUE` if the URI was set successfully, else `FALSE`.

## Types and Values

### GstURIHandler

    typedef struct _GstURIHandler GstURIHandler;

Opaque GstURIHandler structure.

### struct GstURIHandlerInterface

    struct GstURIHandlerInterface {
      GTypeInterface parent;

      /* vtable */
      /* querying capabilities */
      GstURIType             (* get_type)           (GType type);
      const gchar * const *  (* get_protocols)      (GType type);

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

Any GstElement using this interface should implement these methods.

#### Members

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

### enum GstURIType

The different types of URI direction.

#### Members

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

### enum GstURIError

Different URI-related errors that can occur.

#### Members

GST_URI_ERROR_UNSUPPORTED_PROTOCOL | The protocol is not supported |
GST_URI_ERROR_BAD_URI | There was a problem with the URI |
GST_URI_ERROR_BAD_STATE | Could not set or change the URI because the URI handler was in a state where that is not possible or not permitted |
GST_URI_ERROR_BAD_REFERENCE | There was a problem with the entity that the URI references |

### GST_URI_NO_PORT

    #define GST_URI_NO_PORT 0

Value for GstUri.port to indicate no port number.