GstUriHandler

GstUriHandler — Interface to ease URI handling in plugins.

Synopsis

#include <gst/gst.h>

                    GstURIHandler;
struct              GstURIHandlerInterface;
enum                GstURIType;
enum                GstURIError;
GQuark              gst_uri_error_quark                 (void);
#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);
gchar *             gst_filename_to_uri                 (const gchar *filename,
                                                         GError **error);
GstElement *        gst_element_make_from_uri           (const GstURIType type,
                                                         const gchar *uri,
                                                         const gchar *elementname,
                                                         GError **error);
GstURIType          gst_uri_handler_get_uri_type        (GstURIHandler *handler);
const gchar * const * 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,
                                                         GError **error);

Object Hierarchy

  GInterface
   +----GstURIHandler

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.

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.

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

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.

enum GstURIError

typedef enum {
  GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
  GST_URI_ERROR_BAD_URI,
  GST_URI_ERROR_BAD_STATE,
  GST_URI_ERROR_BAD_REFERENCE
} GstURIError;

Different URI-related errors that can occur.

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

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.

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

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.

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 :

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

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

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

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.

filename :

 absolute or relative file name path

error :

 pointer to error, or NULL

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.

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

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.

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]

gst_uri_handler_get_uri ()

gchar *             gst_uri_handler_get_uri             (GstURIHandler *handler);

Gets the currently handled URI.

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]

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.

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.
Generated by GTK-Doc V1.19