1/* GStreamer
2 * Copyright (C) 1999,2000 Erik Walthinsen <[email protected]>
3 * 2000 Wim Taymans <[email protected]>
4 * 2014 David Waring, British Broadcasting Corporation
5 * <[email protected]>
6 *
7 * gsturi.h: Header for uri to element mappings and URI manipulation.
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
18 *
19 * You should have received a copy of the GNU Library General Public
20 * License along with this library; if not, write to the
21 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
22 * Boston, MA 02110-1301, USA.
23 */
24
25
26#ifndef __GST_URI_H__
27#define __GST_URI_H__
28
29#include <glib.h>
30#include <glib-object.h>
31
32G_BEGIN_DECLS
33
34#include <gst/gstconfig.h>
35
36GST_API
37GQuark gst_uri_error_quark (void);
38
39/**
40 * GST_URI_ERROR:
41 *
42 * Get access to the error quark of the uri subsystem.
43 */
44#define GST_URI_ERROR gst_uri_error_quark ()
45
46/**
47 * GstURIError:
48 * @GST_URI_ERROR_UNSUPPORTED_PROTOCOL: The protocol is not supported
49 * @GST_URI_ERROR_BAD_URI: There was a problem with the URI
50 * @GST_URI_ERROR_BAD_STATE: Could not set or change the URI because the
51 * URI handler was in a state where that is not possible or not permitted
52 * @GST_URI_ERROR_BAD_REFERENCE: There was a problem with the entity that
53 * the URI references
54 *
55 * Different URI-related errors that can occur.
56 */
57typedef enum
58{
59 GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
60 GST_URI_ERROR_BAD_URI,
61 GST_URI_ERROR_BAD_STATE,
62 GST_URI_ERROR_BAD_REFERENCE
63} GstURIError;
64
65/**
66 * GstURIType:
67 * @GST_URI_UNKNOWN: The URI direction is unknown
68 * @GST_URI_SINK: The URI is a consumer.
69 * @GST_URI_SRC: The URI is a producer.
70 *
71 * The different types of URI direction.
72 */
73
74typedef enum {
75 GST_URI_UNKNOWN,
76 GST_URI_SINK,
77 GST_URI_SRC
78} GstURIType;
79
80/**
81 * GST_URI_TYPE_IS_VALID:
82 * @type: A #GstURIType
83 *
84 * Tests if the type direction is valid.
85 */
86#define GST_URI_TYPE_IS_VALID(type) ((type) == GST_URI_SRC || (type) == GST_URI_SINK)
87
88/* uri handler functions */
89#define GST_TYPE_URI_HANDLER (gst_uri_handler_get_type ())
90#define GST_URI_HANDLER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_URI_HANDLER, GstURIHandler))
91#define GST_IS_URI_HANDLER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_URI_HANDLER))
92#define GST_URI_HANDLER_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GST_TYPE_URI_HANDLER, GstURIHandlerInterface))
93
94/**
95 * GstURIHandler:
96 *
97 * Opaque #GstURIHandler structure.
98 */
99typedef struct _GstURIHandler GstURIHandler;
100typedef struct _GstURIHandlerInterface GstURIHandlerInterface;
101
102#include <gst/gstelement.h>
103#include "gstminiobject.h"
104
105/**
106 * GstURIHandlerInterface:
107 * @parent: The parent interface type
108 * @get_type: Method to tell whether the element handles source or sink URI.
109 * @get_protocols: Method to return the list of protocols handled by the element.
110 * @get_uri: Method to return the URI currently handled by the element.
111 * @set_uri: Method to set a new URI.
112 *
113 * Any #GstElement using this interface should implement these methods.
114 */
115struct _GstURIHandlerInterface {
116 GTypeInterface parent;
117
118 /* vtable */
119 /*< public >*/
120 /* querying capabilities */
121 GstURIType (* get_type) (GType type);
122 const gchar * const * (* get_protocols) (GType type);
123
124 /* using the interface */
125 gchar * (* get_uri) (GstURIHandler * handler);
126 gboolean (* set_uri) (GstURIHandler * handler,
127 const gchar * uri,
128 GError ** error);
129};
130
131/* general URI functions */
132
133GST_API
134gboolean gst_uri_protocol_is_valid (const gchar * protocol);
135
136GST_API
137gboolean gst_uri_protocol_is_supported (const GstURIType type,
138 const gchar *protocol);
139GST_API
140gboolean gst_uri_is_valid (const gchar * uri);
141
142GST_API
143gchar * gst_uri_get_protocol (const gchar * uri) G_GNUC_MALLOC;
144
145GST_API
146gboolean gst_uri_has_protocol (const gchar * uri,
147 const gchar * protocol);
148GST_API
149gchar * gst_uri_get_location (const gchar * uri) G_GNUC_MALLOC;
150
151GST_DEPRECATED_FOR(gst_uri_new)
152gchar * gst_uri_construct (const gchar * protocol,
153 const gchar * location) G_GNUC_MALLOC;
154GST_API
155gchar * gst_filename_to_uri (const gchar * filename,
156 GError ** error) G_GNUC_MALLOC;
157GST_API
158GstElement * gst_element_make_from_uri (const GstURIType type,
159 const gchar * uri,
160 const gchar * elementname,
161 GError ** error) G_GNUC_MALLOC;
162
163/* accessing the interface */
164
165GST_API
166GType gst_uri_handler_get_type (void);
167
168GST_API
169GstURIType gst_uri_handler_get_uri_type (GstURIHandler * handler);
170
171GST_API
172const gchar * const * gst_uri_handler_get_protocols (GstURIHandler * handler);
173
174GST_API
175gchar * gst_uri_handler_get_uri (GstURIHandler * handler) G_GNUC_MALLOC;
176
177GST_API
178gboolean gst_uri_handler_set_uri (GstURIHandler * handler,
179 const gchar * uri,
180 GError ** error);
181
182/*
183 * GstUri Type macros.
184 */
185#define GST_TYPE_URI (gst_uri_get_type ())
186#define GST_IS_URI(obj) (GST_IS_MINI_OBJECT_TYPE (obj, GST_TYPE_URI))
187#define GST_URI_CAST(obj) ((GstUri *)(obj))
188#define GST_URI_CONST_CAST(obj) ((const GstUri *)(obj))
189#define GST_URI(obj) (GST_URI_CAST(obj))
190
191/**
192 * GstUri:
193 *
194 * This is a private structure that holds the various parts of a parsed URI.
195 */
196struct _GstUri;
197typedef struct _GstUri GstUri;
198
199/**
200 * GST_URI_NO_PORT:
201 *
202 * Value for #GstUri<!-- -->.port to indicate no port number.
203 */
204#define GST_URI_NO_PORT 0
205
206/* used by GST_TYPE_URI */
207
208GST_API
209GType gst_uri_get_type (void);
210
211/*
212 * Method definitions.
213 */
214
215GST_API
216GstUri * gst_uri_new (const gchar * scheme,
217 const gchar * userinfo,
218 const gchar * host,
219 guint port,
220 const gchar * path,
221 const gchar * query,
222 const gchar * fragment) G_GNUC_MALLOC;
223GST_API
224GstUri * gst_uri_new_with_base (GstUri * base,
225 const gchar * scheme,
226 const gchar * userinfo,
227 const gchar * host,
228 guint port,
229 const gchar * path,
230 const gchar * query,
231 const gchar * fragment) G_GNUC_MALLOC;
232GST_API
233GstUri * gst_uri_from_string (const gchar * uri) G_GNUC_MALLOC;
234
235GST_API
236GstUri * gst_uri_from_string_with_base (GstUri * base,
237 const gchar * uri) G_GNUC_MALLOC;
238GST_API
239gboolean gst_uri_equal (const GstUri * first,
240 const GstUri * second);
241GST_API
242GstUri * gst_uri_join (GstUri * base_uri,
243 GstUri * ref_uri) G_GNUC_WARN_UNUSED_RESULT;
244GST_API
245gchar * gst_uri_join_strings (const gchar * base_uri,
246 const gchar * ref_uri) G_GNUC_MALLOC;
247GST_API
248gboolean gst_uri_is_writable (const GstUri * uri);
249
250GST_API
251GstUri * gst_uri_make_writable (GstUri * uri) G_GNUC_WARN_UNUSED_RESULT;
252
253GST_API
254gchar * gst_uri_to_string (const GstUri * uri) G_GNUC_MALLOC;
255
256GST_API
257gboolean gst_uri_is_normalized (const GstUri * uri);
258
259GST_API
260gboolean gst_uri_normalize (GstUri * uri);
261
262GST_API
263const gchar * gst_uri_get_scheme (const GstUri * uri);
264
265GST_API
266gboolean gst_uri_set_scheme (GstUri * uri, const gchar * scheme);
267
268GST_API
269const gchar * gst_uri_get_userinfo (const GstUri * uri);
270
271GST_API
272gboolean gst_uri_set_userinfo (GstUri * uri, const gchar * userinfo);
273
274GST_API
275const gchar * gst_uri_get_host (const GstUri * uri);
276
277GST_API
278gboolean gst_uri_set_host (GstUri * uri, const gchar * host);
279
280GST_API
281guint gst_uri_get_port (const GstUri * uri);
282
283GST_API
284gboolean gst_uri_set_port (GstUri * uri, guint port);
285
286GST_API
287gchar * gst_uri_get_path (const GstUri * uri);
288
289GST_API
290gboolean gst_uri_set_path (GstUri * uri, const gchar * path);
291
292GST_API
293gchar * gst_uri_get_path_string (const GstUri * uri);
294
295GST_API
296gboolean gst_uri_set_path_string (GstUri * uri, const gchar * path);
297
298GST_API
299GList * gst_uri_get_path_segments (const GstUri * uri);
300
301GST_API
302gboolean gst_uri_set_path_segments (GstUri * uri, GList * path_segments);
303
304GST_API
305gboolean gst_uri_append_path (GstUri * uri,
306 const gchar * relative_path);
307GST_API
308gboolean gst_uri_append_path_segment (GstUri * uri,
309 const gchar * path_segment);
310GST_API
311gchar * gst_uri_get_query_string (const GstUri * uri);
312
313GST_API
314gboolean gst_uri_set_query_string (GstUri * uri, const gchar * query);
315
316GST_API
317GHashTable * gst_uri_get_query_table (const GstUri * uri);
318
319GST_API
320gboolean gst_uri_set_query_table (GstUri * uri,
321 GHashTable * query_table);
322GST_API
323gboolean gst_uri_set_query_value (GstUri * uri, const gchar * query_key,
324 const gchar * query_value);
325GST_API
326gboolean gst_uri_remove_query_key (GstUri * uri, const gchar * query_key);
327
328GST_API
329gboolean gst_uri_query_has_key (const GstUri * uri,
330 const gchar * query_key);
331
332GST_API
333const gchar * gst_uri_get_query_value (const GstUri * uri,
334 const gchar * query_key);
335
336GST_API
337GList * gst_uri_get_query_keys (const GstUri * uri);
338
339GST_API
340const gchar * gst_uri_get_fragment (const GstUri * uri);
341
342GST_API
343gboolean gst_uri_set_fragment (GstUri * uri, const gchar * fragment);
344
345GST_API
346GHashTable * gst_uri_get_media_fragment_table (const GstUri * uri);
347
348/**
349 * gst_uri_copy:
350 * @uri: This #GstUri object.
351 *
352 * Create a new #GstUri object with the same data as this #GstUri object.
353 * If @uri is %NULL then returns %NULL.
354 *
355 * Returns: (transfer full): A new #GstUri object which is a copy of this
356 * #GstUri or %NULL.
357 */
358static inline GstUri *
359gst_uri_copy (const GstUri * uri)
360{
361 return GST_URI_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (uri)));
362}
363
364/**
365 * gst_uri_ref:
366 * @uri: (transfer none): This #GstUri object.
367 *
368 * Add a reference to this #GstUri object. See gst_mini_object_ref() for further
369 * info.
370 *
371 * Returns: This object with the reference count incremented.
372 */
373static inline GstUri *
374gst_uri_ref (GstUri * uri)
375{
376 return GST_URI_CAST (gst_mini_object_ref (GST_MINI_OBJECT_CAST (uri)));
377}
378
379/**
380 * gst_uri_unref:
381 * @uri: (transfer full): This #GstUri object.
382 *
383 * Decrement the reference count to this #GstUri object.
384 *
385 * If the reference count drops to 0 then finalize this object.
386 *
387 * See gst_mini_object_unref() for further info.
388 */
389static inline void
390gst_uri_unref (GstUri * uri)
391{
392 gst_mini_object_unref (GST_MINI_OBJECT_CAST (uri));
393}
394
395#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
396G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstUri, gst_uri_unref)
397#endif
398
399G_END_DECLS
400
401#endif /* __GST_URI_H__ */
402