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