1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Toc;
26 
27 private import glib.ConstructionException;
28 private import glib.ListG;
29 private import glib.Str;
30 private import gobject.ObjectG;
31 private import gstreamer.TagList;
32 private import gstreamer.TocEntry;
33 private import gstreamer.c.functions;
34 public  import gstreamer.c.types;
35 public  import gstreamerc.gstreamertypes;
36 
37 
38 /**
39  * #GstToc functions are used to create/free #GstToc and #GstTocEntry structures.
40  * Also they are used to convert #GstToc into #GstStructure and vice versa.
41  * 
42  * #GstToc lets you to inform other elements in pipeline or application that playing
43  * source has some kind of table of contents (TOC). These may be chapters, editions,
44  * angles or other types. For example: DVD chapters, Matroska chapters or cue sheet
45  * TOC. Such TOC will be useful for applications to display instead of just a
46  * playlist.
47  * 
48  * Using TOC is very easy. Firstly, create #GstToc structure which represents root
49  * contents of the source. You can also attach TOC-specific tags to it. Then fill
50  * it with #GstTocEntry entries by appending them to the #GstToc using
51  * gst_toc_append_entry(), and appending subentries to a #GstTocEntry using
52  * gst_toc_entry_append_sub_entry().
53  * 
54  * Note that root level of the TOC can contain only either editions or chapters. You
55  * should not mix them together at the same level. Otherwise you will get serialization
56  * /deserialization errors. Make sure that no one of the entries has negative start and
57  * stop values.
58  * 
59  * Use gst_event_new_toc() to create a new TOC #GstEvent, and gst_event_parse_toc() to
60  * parse received TOC event. Use gst_event_new_toc_select() to create a new TOC select #GstEvent,
61  * and gst_event_parse_toc_select() to parse received TOC select event. The same rule for
62  * the #GstMessage: gst_message_new_toc() to create new TOC #GstMessage, and
63  * gst_message_parse_toc() to parse received TOC message.
64  * 
65  * TOCs can have global scope or current scope. Global scope TOCs contain
66  * all entries that can possibly be selected using a toc select event, and
67  * are what an application is usually interested in. TOCs with current scope
68  * only contain the parts of the TOC relevant to the currently selected/playing
69  * stream; the current scope TOC is used by downstream elements such as muxers
70  * to write correct TOC entries when transcoding files, for example. When
71  * playing a DVD, the global TOC would contain a hierarchy of all titles,
72  * chapters and angles, for example, while the current TOC would only contain
73  * the chapters for the currently playing title if playback of a specific
74  * title was requested.
75  * 
76  * Applications and plugins should not rely on TOCs having a certain kind of
77  * structure, but should allow for different alternatives. For example, a
78  * simple CUE sheet embedded in a file may be presented as a flat list of
79  * track entries, or could have a top-level edition node (or some other
80  * alternative type entry) with track entries underneath that node; or even
81  * multiple top-level edition nodes (or some other alternative type entries)
82  * each with track entries underneath, in case the source file has extracted
83  * a track listing from different sources).
84  */
85 public class Toc
86 {
87 	/** the main Gtk struct */
88 	protected GstToc* gstToc;
89 	protected bool ownedRef;
90 
91 	/** Get the main Gtk struct */
92 	public GstToc* getTocStruct(bool transferOwnership = false)
93 	{
94 		if (transferOwnership)
95 			ownedRef = false;
96 		return gstToc;
97 	}
98 
99 	/** the main Gtk struct as a void* */
100 	protected void* getStruct()
101 	{
102 		return cast(void*)gstToc;
103 	}
104 
105 	/**
106 	 * Sets our main struct and passes it to the parent class.
107 	 */
108 	public this (GstToc* gstToc, bool ownedRef = false)
109 	{
110 		this.gstToc = gstToc;
111 		this.ownedRef = ownedRef;
112 	}
113 
114 
115 	/** */
116 	public static GType getType()
117 	{
118 		return gst_toc_get_type();
119 	}
120 
121 	/**
122 	 * Create a new #GstToc structure.
123 	 *
124 	 * Params:
125 	 *     scop = scope of this TOC
126 	 *
127 	 * Returns: newly allocated #GstToc structure, free it
128 	 *     with gst_toc_unref().
129 	 *
130 	 * Throws: ConstructionException GTK+ fails to create the object.
131 	 */
132 	public this(GstTocScope scop)
133 	{
134 		auto p = gst_toc_new(scop);
135 
136 		if(p is null)
137 		{
138 			throw new ConstructionException("null returned by new");
139 		}
140 
141 		this(cast(GstToc*) p);
142 	}
143 
144 	/**
145 	 * Appends the #GstTocEntry @entry to @toc.
146 	 *
147 	 * Params:
148 	 *     entry = A #GstTocEntry
149 	 */
150 	public void appendEntry(TocEntry entry)
151 	{
152 		gst_toc_append_entry(gstToc, (entry is null) ? null : entry.getTocEntryStruct());
153 	}
154 
155 	/** */
156 	public void dump()
157 	{
158 		gst_toc_dump(gstToc);
159 	}
160 
161 	/**
162 	 * Find #GstTocEntry with given @uid in the @toc.
163 	 *
164 	 * Params:
165 	 *     uid = UID to find #GstTocEntry with.
166 	 *
167 	 * Returns: #GstTocEntry with specified
168 	 *     @uid from the @toc, or %NULL if not found.
169 	 */
170 	public TocEntry findEntry(string uid)
171 	{
172 		auto p = gst_toc_find_entry(gstToc, Str.toStringz(uid));
173 
174 		if(p is null)
175 		{
176 			return null;
177 		}
178 
179 		return ObjectG.getDObject!(TocEntry)(cast(GstTocEntry*) p);
180 	}
181 
182 	/**
183 	 * Gets the list of #GstTocEntry of @toc.
184 	 *
185 	 * Returns: A #GList of #GstTocEntry for @entry
186 	 */
187 	public ListG getEntries()
188 	{
189 		auto p = gst_toc_get_entries(gstToc);
190 
191 		if(p is null)
192 		{
193 			return null;
194 		}
195 
196 		return new ListG(cast(GList*) p);
197 	}
198 
199 	/**
200 	 * Returns: scope of @toc
201 	 */
202 	public GstTocScope getScope()
203 	{
204 		return gst_toc_get_scope(gstToc);
205 	}
206 
207 	/**
208 	 * Gets the tags for @toc.
209 	 *
210 	 * Returns: A #GstTagList for @entry
211 	 */
212 	public TagList getTags()
213 	{
214 		auto p = gst_toc_get_tags(gstToc);
215 
216 		if(p is null)
217 		{
218 			return null;
219 		}
220 
221 		return ObjectG.getDObject!(TagList)(cast(GstTagList*) p);
222 	}
223 
224 	/**
225 	 * Merge @tags into the existing tags of @toc using @mode.
226 	 *
227 	 * Params:
228 	 *     tags = A #GstTagList or %NULL
229 	 *     mode = A #GstTagMergeMode
230 	 */
231 	public void mergeTags(TagList tags, GstTagMergeMode mode)
232 	{
233 		gst_toc_merge_tags(gstToc, (tags is null) ? null : tags.getTagListStruct(), mode);
234 	}
235 
236 	/**
237 	 * Set a #GstTagList with tags for the complete @toc.
238 	 *
239 	 * Params:
240 	 *     tags = A #GstTagList or %NULL
241 	 */
242 	public void setTags(TagList tags)
243 	{
244 		gst_toc_set_tags(gstToc, (tags is null) ? null : tags.getTagListStruct());
245 	}
246 }