1/* gstreamermm - a C++ wrapper for gstreamer
2 *
3 * Copyright 2008 The gstreamermm Development Team
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free
17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 */
19
20#include <gst/gst.h>
21
22_DEFS(gstreamermm,gst)
23
24namespace Gst
25{
26
27class Element;
28
29/** The different parsing errors that can occur.
30 *
31 * - SYNTAX - A syntax error occured.
32 * - NO_SUCH_ELEMENT - The description contained an unknown element
33 * - NO_SUCH_PROPERTY - An element did not have a specified property
34 * - LINK - There was an error linking two pads.
35 * - COULD_NOT_SET_PROPERTY - There was an error setting a property
36 * - EMPTY_BIN - An empty bin was specified.
37 * - EMPTY - An empty description was specified
38 */
39_WRAP_GERROR(ParseError, GstParseError, GST_PARSE_ERROR)
40
41/** A class that gets a pipeline from a text pipeline description.
42 * The methods in this class allow to create a pipeline based on the syntax
43 * used in the gst-launch utillity.
44 */
45class Parse
46{
47public:
48  /** Get the error quark used by the parsing subsystem.
49   * @return The quark of the parse errors.
50   */
51  static Glib::QueryQuark error_quark();
52
53  /** Create a new pipeline based on command line syntax. Please note that you
54   * might get a return value that is not a null RefPtr<> even though the error
55   * is set. In this case there was a recoverable parsing error and you can try
56   * to play the pipeline.
57   * @param pipeline_description The command line describing the pipeline.
58   * @return A new element on success, a null RefPtr<> on failure. If more than
59   * one toplevel element is specified by the pipeline_description, all
60   * elements are put into a Gst::Pipeline, which than is returned.
61   * @throw Gst::CoreError
62   * @throw Gst::ParseError
63   */
64  static Glib::RefPtr<Gst::Element> launch(const Glib::ustring& pipeline_description);
65
66  /** Create a new element based on command line syntax. An error does not
67   * mean that the pipeline could not be constructed.
68   * @param argv null-terminated array of arguments.
69   * specified.
70   * @return A new element on success and null on failure.
71   * @throw Gst::CoreError
72   * @throw Gst::ParseError
73   */
74  static Glib::RefPtr<Gst::Element> launchv(const gchar *argv[]);
75
76  /** This is a convenience wrapper around launch() to create a Gst::Bin from a
77   * gst-launch-style pipeline description. See launch() and the gst-launch man
78   * page for details about the syntax. Ghost pads on the bin for unconnected
79   * source or sink pads within the bin can automatically be created (but only
80   * a maximum of one ghost pad for each direction will be created; if you
81   * expect multiple unconnected source pads or multiple unconnected sink pads
82   * and want them all ghosted, you will have to create the ghost pads
83   * yourself).
84   *
85   * @param bin_description Command line describing the bin.
86   * @param ghost_unconnected_pads Whether to automatically create ghost pads
87   * for unconnected source or sink pads within the bin.
88   * @return A newly-created bin, or a null RefPtr<> if an error occurred.
89   * @throw Gst::CoreError
90   * @throw Gst::ParseError
91   */
92  static Glib::RefPtr<Gst::Element> create_bin(const Glib::ustring& bin_description, bool ghost_unconnected_pads);
93};
94
95} // namespace Gst
96