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