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.Poll;
26 
27 private import glib.ConstructionException;
28 private import gobject.ObjectG;
29 private import gstreamer.PollFD;
30 private import gstreamerc.gstreamer;
31 public  import gstreamerc.gstreamertypes;
32 
33 
34 /**
35  * A #GstPoll keeps track of file descriptors much like fd_set (used with
36  * select()) or a struct pollfd array (used with poll()). Once created with
37  * gst_poll_new(), the set can be used to wait for file descriptors to be
38  * readable and/or writable. It is possible to make this wait be controlled
39  * by specifying %TRUE for the @controllable flag when creating the set (or
40  * later calling gst_poll_set_controllable()).
41  * 
42  * New file descriptors are added to the set using gst_poll_add_fd(), and
43  * removed using gst_poll_remove_fd(). Controlling which file descriptors
44  * should be waited for to become readable and/or writable are done using
45  * gst_poll_fd_ctl_read() and gst_poll_fd_ctl_write().
46  * 
47  * Use gst_poll_wait() to wait for the file descriptors to actually become
48  * readable and/or writable, or to timeout if no file descriptor is available
49  * in time. The wait can be controlled by calling gst_poll_restart() and
50  * gst_poll_set_flushing().
51  * 
52  * Once the file descriptor set has been waited for, one can use
53  * gst_poll_fd_has_closed() to see if the file descriptor has been closed,
54  * gst_poll_fd_has_error() to see if it has generated an error,
55  * gst_poll_fd_can_read() to see if it is possible to read from the file
56  * descriptor, and gst_poll_fd_can_write() to see if it is possible to
57  * write to it.
58  */
59 public class Poll
60 {
61 	/** the main Gtk struct */
62 	protected GstPoll* gstPoll;
63 	protected bool ownedRef;
64 
65 	/** Get the main Gtk struct */
66 	public GstPoll* getPollStruct()
67 	{
68 		return gstPoll;
69 	}
70 
71 	/** the main Gtk struct as a void* */
72 	protected void* getStruct()
73 	{
74 		return cast(void*)gstPoll;
75 	}
76 
77 	/**
78 	 * Sets our main struct and passes it to the parent class.
79 	 */
80 	public this (GstPoll* gstPoll, bool ownedRef = false)
81 	{
82 		this.gstPoll = gstPoll;
83 		this.ownedRef = ownedRef;
84 	}
85 
86 
87 	/**
88 	 * Add a file descriptor to the file descriptor set.
89 	 *
90 	 * Params:
91 	 *     fd = a file descriptor.
92 	 *
93 	 * Return: %TRUE if the file descriptor was successfully added to the set.
94 	 */
95 	public bool addFd(PollFD fd)
96 	{
97 		return gst_poll_add_fd(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
98 	}
99 
100 	/**
101 	 * Check if @fd in @set has data to be read.
102 	 *
103 	 * Params:
104 	 *     fd = a file descriptor.
105 	 *
106 	 * Return: %TRUE if the descriptor has data to be read.
107 	 */
108 	public bool fdCanRead(PollFD fd)
109 	{
110 		return gst_poll_fd_can_read(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
111 	}
112 
113 	/**
114 	 * Check if @fd in @set can be used for writing.
115 	 *
116 	 * Params:
117 	 *     fd = a file descriptor.
118 	 *
119 	 * Return: %TRUE if the descriptor can be used for writing.
120 	 */
121 	public bool fdCanWrite(PollFD fd)
122 	{
123 		return gst_poll_fd_can_write(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
124 	}
125 
126 	/**
127 	 * Control whether the descriptor @fd in @set will be monitored for
128 	 * readability.
129 	 *
130 	 * Params:
131 	 *     fd = a file descriptor.
132 	 *     active = a new status.
133 	 *
134 	 * Return: %TRUE if the descriptor was successfully updated.
135 	 */
136 	public bool fdCtlRead(PollFD fd, bool active)
137 	{
138 		return gst_poll_fd_ctl_read(gstPoll, (fd is null) ? null : fd.getPollFDStruct(), active) != 0;
139 	}
140 
141 	/**
142 	 * Control whether the descriptor @fd in @set will be monitored for
143 	 * writability.
144 	 *
145 	 * Params:
146 	 *     fd = a file descriptor.
147 	 *     active = a new status.
148 	 *
149 	 * Return: %TRUE if the descriptor was successfully updated.
150 	 */
151 	public bool fdCtlWrite(PollFD fd, bool active)
152 	{
153 		return gst_poll_fd_ctl_write(gstPoll, (fd is null) ? null : fd.getPollFDStruct(), active) != 0;
154 	}
155 
156 	/**
157 	 * Check if @fd in @set has closed the connection.
158 	 *
159 	 * Params:
160 	 *     fd = a file descriptor.
161 	 *
162 	 * Return: %TRUE if the connection was closed.
163 	 */
164 	public bool fdHasClosed(PollFD fd)
165 	{
166 		return gst_poll_fd_has_closed(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
167 	}
168 
169 	/**
170 	 * Check if @fd in @set has an error.
171 	 *
172 	 * Params:
173 	 *     fd = a file descriptor.
174 	 *
175 	 * Return: %TRUE if the descriptor has an error.
176 	 */
177 	public bool fdHasError(PollFD fd)
178 	{
179 		return gst_poll_fd_has_error(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
180 	}
181 
182 	/**
183 	 * Mark @fd as ignored so that the next call to gst_poll_wait() will yield
184 	 * the same result for @fd as last time. This function must be called if no
185 	 * operation (read/write/recv/send/etc.) will be performed on @fd before
186 	 * the next call to gst_poll_wait().
187 	 *
188 	 * The reason why this is needed is because the underlying implementation
189 	 * might not allow querying the fd more than once between calls to one of
190 	 * the re-enabling operations.
191 	 *
192 	 * Params:
193 	 *     fd = a file descriptor.
194 	 */
195 	public void fdIgnored(PollFD fd)
196 	{
197 		gst_poll_fd_ignored(gstPoll, (fd is null) ? null : fd.getPollFDStruct());
198 	}
199 
200 	/**
201 	 * Free a file descriptor set.
202 	 */
203 	public void free()
204 	{
205 		gst_poll_free(gstPoll);
206 	}
207 
208 	/**
209 	 * Get a GPollFD for the reading part of the control socket. This is useful when
210 	 * integrating with a GSource and GMainLoop.
211 	 *
212 	 * Params:
213 	 *     fd = a #GPollFD
214 	 */
215 	public void getReadGpollfd(GPollFD* fd)
216 	{
217 		gst_poll_get_read_gpollfd(gstPoll, fd);
218 	}
219 
220 	/**
221 	 * Read a byte from the control socket of the controllable @set.
222 	 * This function is mostly useful for timer #GstPoll objects created with
223 	 * gst_poll_new_timer().
224 	 *
225 	 * Return: %TRUE on success. %FALSE when @set is not controllable or when there
226 	 *     was no byte to read.
227 	 */
228 	public bool readControl()
229 	{
230 		return gst_poll_read_control(gstPoll) != 0;
231 	}
232 
233 	/**
234 	 * Remove a file descriptor from the file descriptor set.
235 	 *
236 	 * Params:
237 	 *     fd = a file descriptor.
238 	 *
239 	 * Return: %TRUE if the file descriptor was successfully removed from the set.
240 	 */
241 	public bool removeFd(PollFD fd)
242 	{
243 		return gst_poll_remove_fd(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
244 	}
245 
246 	/**
247 	 * Restart any gst_poll_wait() that is in progress. This function is typically
248 	 * used after adding or removing descriptors to @set.
249 	 *
250 	 * If @set is not controllable, then this call will have no effect.
251 	 */
252 	public void restart()
253 	{
254 		gst_poll_restart(gstPoll);
255 	}
256 
257 	/**
258 	 * When @controllable is %TRUE, this function ensures that future calls to
259 	 * gst_poll_wait() will be affected by gst_poll_restart() and
260 	 * gst_poll_set_flushing().
261 	 *
262 	 * Params:
263 	 *     controllable = new controllable state.
264 	 *
265 	 * Return: %TRUE if the controllability of @set could be updated.
266 	 */
267 	public bool setControllable(bool controllable)
268 	{
269 		return gst_poll_set_controllable(gstPoll, controllable) != 0;
270 	}
271 
272 	/**
273 	 * When @flushing is %TRUE, this function ensures that current and future calls
274 	 * to gst_poll_wait() will return -1, with errno set to EBUSY.
275 	 *
276 	 * Unsetting the flushing state will restore normal operation of @set.
277 	 *
278 	 * Params:
279 	 *     flushing = new flushing state.
280 	 */
281 	public void setFlushing(bool flushing)
282 	{
283 		gst_poll_set_flushing(gstPoll, flushing);
284 	}
285 
286 	/**
287 	 * Wait for activity on the file descriptors in @set. This function waits up to
288 	 * the specified @timeout.  A timeout of #GST_CLOCK_TIME_NONE waits forever.
289 	 *
290 	 * For #GstPoll objects created with gst_poll_new(), this function can only be
291 	 * called from a single thread at a time.  If called from multiple threads,
292 	 * -1 will be returned with errno set to EPERM.
293 	 *
294 	 * This is not true for timer #GstPoll objects created with
295 	 * gst_poll_new_timer(), where it is allowed to have multiple threads waiting
296 	 * simultaneously.
297 	 *
298 	 * Params:
299 	 *     timeout = a timeout in nanoseconds.
300 	 *
301 	 * Return: The number of #GstPollFD in @set that have activity or 0 when no
302 	 *     activity was detected after @timeout. If an error occurs, -1 is returned
303 	 *     and errno is set.
304 	 */
305 	public int wait(GstClockTime timeout)
306 	{
307 		return gst_poll_wait(gstPoll, timeout);
308 	}
309 
310 	/**
311 	 * Write a byte to the control socket of the controllable @set.
312 	 * This function is mostly useful for timer #GstPoll objects created with
313 	 * gst_poll_new_timer().
314 	 *
315 	 * It will make any current and future gst_poll_wait() function return with
316 	 * 1, meaning the control socket is set. After an equal amount of calls to
317 	 * gst_poll_read_control() have been performed, calls to gst_poll_wait() will
318 	 * block again until their timeout expired.
319 	 *
320 	 * Return: %TRUE on success. %FALSE when @set is not controllable or when the
321 	 *     byte could not be written.
322 	 */
323 	public bool writeControl()
324 	{
325 		return gst_poll_write_control(gstPoll) != 0;
326 	}
327 
328 	/**
329 	 * Create a new file descriptor set. If @controllable, it
330 	 * is possible to restart or flush a call to gst_poll_wait() with
331 	 * gst_poll_restart() and gst_poll_set_flushing() respectively.
332 	 *
333 	 * Free-function: gst_poll_free
334 	 *
335 	 * Params:
336 	 *     controllable = whether it should be possible to control a wait.
337 	 *
338 	 * Return: a new #GstPoll, or %NULL in
339 	 *     case of an error.  Free with gst_poll_free().
340 	 *
341 	 * Throws: ConstructionException GTK+ fails to create the object.
342 	 */
343 	public this(bool controllable)
344 	{
345 		auto p = gst_poll_new(controllable);
346 		
347 		if(p is null)
348 		{
349 			throw new ConstructionException("null returned by new");
350 		}
351 		
352 		this(cast(GstPoll*) p);
353 	}
354 
355 	/**
356 	 * Create a new poll object that can be used for scheduling cancellable
357 	 * timeouts.
358 	 *
359 	 * A timeout is performed with gst_poll_wait(). Multiple timeouts can be
360 	 * performed from different threads.
361 	 *
362 	 * Free-function: gst_poll_free
363 	 *
364 	 * Return: a new #GstPoll, or %NULL in
365 	 *     case of an error.  Free with gst_poll_free().
366 	 *
367 	 * Throws: ConstructionException GTK+ fails to create the object.
368 	 */
369 	public this()
370 	{
371 		auto p = gst_poll_new_timer();
372 		
373 		if(p is null)
374 		{
375 			throw new ConstructionException("null returned by new_timer");
376 		}
377 		
378 		this(cast(GstPoll*) p);
379 	}
380 }