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