GstUriHandler

GstUriHandler — Interface to ease URI handling in plugins.

Functions

Signals

void new-uri Run Last

Types and Values

Object Hierarchy

    GInterface
    ╰── GstURIHandler

Includes

#include <gst/gst.h>

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)

Functions

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

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

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

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][array zero-terminated=1]


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.

[array zero-terminated=1][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][array zero-terminated=1]


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

 

Since: 0.10.33


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.

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]

Returns

a new element or NULL if none could be created.

[transfer full]


gst_uri_handler_get_uri_type ()

guint
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 ()

gchar **
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][array zero-terminated=1][element-type utf8]


gst_uri_handler_get_uri ()

const 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 not be modified or freed.

[transfer none]


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.

Parameters

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.

Parameters

handler

A GstURIHandler

 

uri

new URI or NULL if it was unset

 

Types and Values

GstURIHandler

typedef struct _GstURIHandler GstURIHandler;

Opaque GstURIHandler structure.


struct GstURIHandlerInterface

struct GstURIHandlerInterface {
  GTypeInterface parent;

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

  /* using the interface */
  const 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);
};

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.

 

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

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.

 

Signal Details

The “new-uri” signal

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

The URI of the given handler has changed.

Parameters

handler

The GstURIHandler which emitted the signal

 

uri

The new URI, or NULL if the URI was removed.

[transfer none]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last