Gst::URIHandler Class Reference
gstreamermm Interfaces

An interface to ease URI handling in plugins. More...

`#include <gstreamermm/urihandler.h>`

Inherits Interface.

## Public Member Functions

| URIHandler (URIHandler&& src) noexcept
URIHandler& | operator= (URIHandler&& src) noexcept
| ~URIHandler () noexcept override
GstURIHandler* | gobj ()
| Provides access to the underlying C GObject. More...
const GstURIHandler* | gobj () const
| Provides access to the underlying C GObject. More...
URIType | get_uri_type () const
| Gets the type of the given URI handler. More...
std::vector< Glib::ustring > | get_protocols () const
| Gets the list of protocols supported by handler. More...
Glib::ustring | get_uri () const
| Gets the currently handled URI. More...
bool | set_uri (const Glib::ustring& uri)
| Tries to set the URI of the given handler. More...
virtual Glib::ustring | get_uri_vfunc () const
| Virtual method which should be implemented to return the URI currently handled by the element. More...
virtual bool | set_uri_vfunc (const Glib::ustring& uri, GError** error)
| Virtual method which should be implemented to set a new URI. More...
virtual const gchar* const * | get_protocols_vfunc () const
| Method to return the list of protocols handled by the element. More...
virtual URIType | get_type_vfunc ()
| Method to tell whether the element handles source or sink URI. More...

## Static Public Member Functions

static void | add_interface (GType gtype_implementer)
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static bool | protocol_is_valid (const Glib::ustring& protocol)
| Tests if the given string is a valid protocol identifier. More...
static bool | protocol_is_supported (const Gst::URIType type, const Glib::ustring& protocol)
| Checks if an element exists that supports the given URI protocol. More...
static bool | uri_is_valid (const Glib::ustring& uri)
| Tests if the given string is a valid URI identifier. More...
static bool | uri_has_protocol (const Glib::ustring& uri, const Glib::ustring& protocol)
| Checks if the protocol of a given valid URI matches protocol. More...
static Glib::ustring | get_protocol (const Glib::ustring& uri)
| Extracts the protocol out of a given valid URI. More...
static Glib::ustring | get_location (const Glib::ustring& uri)
| Extracts the location out of a given valid URI, ie. More...
static Glib::ustring | construct_uri (const Glib::ustring& protocol, const Glib::ustring& location)
| Constructs a URI for a given valid protocol and location. More...
static Glib::ustring | filename_to_uri (const Glib::ustring& filename)
| Similar to Glib::filename_to_uri(), but attempts to handle relative file paths as well. More...
static Glib::RefPtr< Gst::Element > | make_element_from_uri (const Gst::URIType type, const Glib::ustring& uri, const Glib::ustring& name)
| Creates an element for handling the given URI. More...

## Protected Member Functions

| URIHandler ()
| You should derive from this class to use it. More...

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gst::URIHandler > | wrap (GstURIHandler* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

An interface to ease URI handling in plugins.

The Gst::URIHandler is an interface that is implemented by Source and Sink Gst::Element 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 (make_element_from_uri()).

Source and Sink plugins should implement this interface when possible.

Last reviewed on 2016-08-27 (1.8.0)

## Constructor & Destructor Documentation

## URIHandler() [1/2]

Gst::URIHandler::URIHandler | ( |  | ) |

protected

You should derive from this class to use it.

## URIHandler() [2/2]

Gst::URIHandler::URIHandler | ( | URIHandler&& | src | ) |

noexcept

## ~URIHandler()

Gst::URIHandler::~URIHandler | ( |  | ) |

override noexcept

## Member Function Documentation

## add_interface()

static void Gst::URIHandler::add_interface | ( | GType | gtype_implementer | ) |

static

## construct_uri()

static Glib::ustring Gst::URIHandler::construct_uri | ( | const Glib::ustring & | protocol,
|  | const Glib::ustring & | location
| ) |  |

static

Constructs a URI for a given valid protocol and location.

Parameters

  protocol | Protocol for URI.
  location | Location for URI.

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

## filename_to_uri()

static Glib::ustring Gst::URIHandler::filename_to_uri | ( | const Glib::ustring & | filename | ) |

static

Similar to Glib::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.

Returns
  Newly-allocated URI string, or `nullptr` on error.

## get_location()

static Glib::ustring Gst::URIHandler::get_location | ( | const Glib::ustring & | uri | ) |

static

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.

Free-function: g_free

Parameters

  uri | A URI string.

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

## get_protocol()

static Glib::ustring Gst::URIHandler::get_protocol | ( | const Glib::ustring & | uri | ) |

static

Extracts the protocol out of a given valid URI.

Parameters

  uri | A URI string.

Returns
  The protocol for this URI.

## get_protocols()

std::vector<Glib::ustring> Gst::URIHandler::get_protocols | ( |  | ) | const

Gets the list of protocols supported by handler.

This list may not be modified.

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

## get_protocols_vfunc()

virtual const gchar* const* Gst::URIHandler::get_protocols_vfunc | ( |  | ) | const

virtual

Method to return the list of protocols handled by the element.

## get_type()

static GType Gst::URIHandler::get_type | ( |  | ) |

static

Get the GType for this class, for use with the underlying GObject type system.

## get_type_vfunc()

virtual URIType Gst::URIHandler::get_type_vfunc | ( |  | ) |

virtual

Method to tell whether the element handles source or sink URI.

## get_uri()

Glib::ustring Gst::URIHandler::get_uri | ( |  | ) | const

Gets the currently handled URI.

Returns
  The URI currently handled by the handler. Returns `nullptr` if there are no URI currently handled.

## get_uri_type()

URIType Gst::URIHandler::get_uri_type | ( |  | ) | const

Gets the type of the given URI handler.

Returns
  The Gst::URIType of the URI handler. Returns Gst::URI_UNKNOWN if the handler isn't implemented correctly.

## get_uri_vfunc()

virtual Glib::ustring Gst::URIHandler::get_uri_vfunc | ( |  | ) | const

virtual

Virtual method which should be implemented to return the URI currently handled by the element.

## gobj() [1/2]

GstURIHandler* Gst::URIHandler::gobj | ( |  | ) |

inline

Provides access to the underlying C GObject.

## gobj() [2/2]

const GstURIHandler* Gst::URIHandler::gobj | ( |  | ) | const

inline

Provides access to the underlying C GObject.

## make_element_from_uri()

static Glib::RefPtr<Gst::Element> Gst::URIHandler::make_element_from_uri | ( | const Gst::URIType | type,
|  | const Glib::ustring & | uri,
|  | const Glib::ustring & | name
| ) |  |

static

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.
  name | Name of created element, can be `nullptr`.

Returns
  A new element or `nullptr` if none could be created.

## operator=()

URIHandler& Gst::URIHandler::operator= | ( | URIHandler&& | src | ) |

noexcept

## protocol_is_supported()

static bool Gst::URIHandler::protocol_is_supported | ( | const Gst::URIType | type,
|  | const Glib::ustring & | protocol
| ) |  |

static

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

## protocol_is_valid()

static bool Gst::URIHandler::protocol_is_valid | ( | const Glib::ustring & | protocol | ) |

static

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.

## set_uri()

bool Gst::URIHandler::set_uri | ( | const Glib::ustring & | uri | ) |

Tries to set the URI of the given handler.

Parameters

  uri | URI to set.

Returns
  `true` if the URI was set successfully, else `false`.

## set_uri_vfunc()

virtual bool Gst::URIHandler::set_uri_vfunc | ( | const Glib::ustring & | uri,
|  | GError ** | error
| ) |  |

virtual

Virtual method which should be implemented to set a new URI.

## uri_has_protocol()

static bool Gst::URIHandler::uri_has_protocol | ( | const Glib::ustring & | uri,
|  | const Glib::ustring & | protocol
| ) |  |

static

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.

## uri_is_valid()

static bool Gst::URIHandler::uri_is_valid | ( | const Glib::ustring & | uri | ) |

static

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.

## Friends And Related Function Documentation

## wrap()

Glib::RefPtr< Gst::URIHandler > wrap | ( | GstURIHandler * | object,
|  | bool | take_copy = `false`
| ) |  |

related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.