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() and gst_poll_fd_ctl_write().
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 	 * readability.
139 	 *
140 	 * Params:
141 	 *     fd = a file descriptor.
142 	 *     active = a new status.
143 	 *
144 	 * Returns: %TRUE if the descriptor was successfully updated.
145 	 */
146 	public bool fdCtlRead(PollFD fd, bool active)
147 	{
148 		return gst_poll_fd_ctl_read(gstPoll, (fd is null) ? null : fd.getPollFDStruct(), active) != 0;
149 	}
150 
151 	/**
152 	 * Control whether the descriptor @fd in @set will be monitored for
153 	 * writability.
154 	 *
155 	 * Params:
156 	 *     fd = a file descriptor.
157 	 *     active = a new status.
158 	 *
159 	 * Returns: %TRUE if the descriptor was successfully updated.
160 	 */
161 	public bool fdCtlWrite(PollFD fd, bool active)
162 	{
163 		return gst_poll_fd_ctl_write(gstPoll, (fd is null) ? null : fd.getPollFDStruct(), active) != 0;
164 	}
165 
166 	/**
167 	 * Check if @fd in @set has closed the connection.
168 	 *
169 	 * Params:
170 	 *     fd = a file descriptor.
171 	 *
172 	 * Returns: %TRUE if the connection was closed.
173 	 */
174 	public bool fdHasClosed(PollFD fd)
175 	{
176 		return gst_poll_fd_has_closed(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
177 	}
178 
179 	/**
180 	 * Check if @fd in @set has an error.
181 	 *
182 	 * Params:
183 	 *     fd = a file descriptor.
184 	 *
185 	 * Returns: %TRUE if the descriptor has an error.
186 	 */
187 	public bool fdHasError(PollFD fd)
188 	{
189 		return gst_poll_fd_has_error(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
190 	}
191 
192 	/**
193 	 * Mark @fd as ignored so that the next call to gst_poll_wait() will yield
194 	 * the same result for @fd as last time. This function must be called if no
195 	 * operation (read/write/recv/send/etc.) will be performed on @fd before
196 	 * the next call to gst_poll_wait().
197 	 *
198 	 * The reason why this is needed is because the underlying implementation
199 	 * might not allow querying the fd more than once between calls to one of
200 	 * the re-enabling operations.
201 	 *
202 	 * Params:
203 	 *     fd = a file descriptor.
204 	 */
205 	public void fdIgnored(PollFD fd)
206 	{
207 		gst_poll_fd_ignored(gstPoll, (fd is null) ? null : fd.getPollFDStruct());
208 	}
209 
210 	/**
211 	 * Free a file descriptor set.
212 	 */
213 	public void free()
214 	{
215 		gst_poll_free(gstPoll);
216 		ownedRef = false;
217 	}
218 
219 	/**
220 	 * Get a GPollFD for the reading part of the control socket. This is useful when
221 	 * integrating with a GSource and GMainLoop.
222 	 *
223 	 * Params:
224 	 *     fd = a #GPollFD
225 	 */
226 	public void getReadGpollfd(GPollFD* fd)
227 	{
228 		gst_poll_get_read_gpollfd(gstPoll, fd);
229 	}
230 
231 	/**
232 	 * Read a byte from the control socket of the controllable @set.
233 	 *
234 	 * This function only works for timer #GstPoll objects created with
235 	 * gst_poll_new_timer().
236 	 *
237 	 * Returns: %TRUE on success. %FALSE when when there was no byte to read or
238 	 *     reading the byte failed. If there was no byte to read, and only then, errno
239 	 *     will contain EWOULDBLOCK or EAGAIN. For all other values of errno this always signals a
240 	 *     critical error.
241 	 */
242 	public bool readControl()
243 	{
244 		return gst_poll_read_control(gstPoll) != 0;
245 	}
246 
247 	/**
248 	 * Remove a file descriptor from the file descriptor set.
249 	 *
250 	 * Params:
251 	 *     fd = a file descriptor.
252 	 *
253 	 * Returns: %TRUE if the file descriptor was successfully removed from the set.
254 	 */
255 	public bool removeFd(PollFD fd)
256 	{
257 		return gst_poll_remove_fd(gstPoll, (fd is null) ? null : fd.getPollFDStruct()) != 0;
258 	}
259 
260 	/**
261 	 * Restart any gst_poll_wait() that is in progress. This function is typically
262 	 * used after adding or removing descriptors to @set.
263 	 *
264 	 * If @set is not controllable, then this call will have no effect.
265 	 *
266 	 * This function only works for non-timer #GstPoll objects created with
267 	 * gst_poll_new().
268 	 */
269 	public void restart()
270 	{
271 		gst_poll_restart(gstPoll);
272 	}
273 
274 	/**
275 	 * When @controllable is %TRUE, this function ensures that future calls to
276 	 * gst_poll_wait() will be affected by gst_poll_restart() and
277 	 * gst_poll_set_flushing().
278 	 *
279 	 * This function only works for non-timer #GstPoll objects created with
280 	 * gst_poll_new().
281 	 *
282 	 * Params:
283 	 *     controllable = new controllable state.
284 	 *
285 	 * Returns: %TRUE if the controllability of @set could be updated.
286 	 */
287 	public bool setControllable(bool controllable)
288 	{
289 		return gst_poll_set_controllable(gstPoll, controllable) != 0;
290 	}
291 
292 	/**
293 	 * When @flushing is %TRUE, this function ensures that current and future calls
294 	 * to gst_poll_wait() will return -1, with errno set to EBUSY.
295 	 *
296 	 * Unsetting the flushing state will restore normal operation of @set.
297 	 *
298 	 * This function only works for non-timer #GstPoll objects created with
299 	 * gst_poll_new().
300 	 *
301 	 * Params:
302 	 *     flushing = new flushing state.
303 	 */
304 	public void setFlushing(bool flushing)
305 	{
306 		gst_poll_set_flushing(gstPoll, flushing);
307 	}
308 
309 	/**
310 	 * Wait for activity on the file descriptors in @set. This function waits up to
311 	 * the specified @timeout.  A timeout of #GST_CLOCK_TIME_NONE waits forever.
312 	 *
313 	 * For #GstPoll objects created with gst_poll_new(), this function can only be
314 	 * called from a single thread at a time.  If called from multiple threads,
315 	 * -1 will be returned with errno set to EPERM.
316 	 *
317 	 * This is not true for timer #GstPoll objects created with
318 	 * gst_poll_new_timer(), where it is allowed to have multiple threads waiting
319 	 * simultaneously.
320 	 *
321 	 * Params:
322 	 *     timeout = a timeout in nanoseconds.
323 	 *
324 	 * Returns: The number of #GstPollFD in @set that have activity or 0 when no
325 	 *     activity was detected after @timeout. If an error occurs, -1 is returned
326 	 *     and errno is set.
327 	 */
328 	public int wait(GstClockTime timeout)
329 	{
330 		return gst_poll_wait(gstPoll, timeout);
331 	}
332 
333 	/**
334 	 * Write a byte to the control socket of the controllable @set.
335 	 * This function is mostly useful for timer #GstPoll objects created with
336 	 * gst_poll_new_timer().
337 	 *
338 	 * It will make any current and future gst_poll_wait() function return with
339 	 * 1, meaning the control socket is set. After an equal amount of calls to
340 	 * gst_poll_read_control() have been performed, calls to gst_poll_wait() will
341 	 * block again until their timeout expired.
342 	 *
343 	 * This function only works for timer #GstPoll objects created with
344 	 * gst_poll_new_timer().
345 	 *
346 	 * Returns: %TRUE on success. %FALSE when when the byte could not be written.
347 	 *     errno contains the detailed error code but will never be EAGAIN, EINTR or
348 	 *     EWOULDBLOCK. %FALSE always signals a critical error.
349 	 */
350 	public bool writeControl()
351 	{
352 		return gst_poll_write_control(gstPoll) != 0;
353 	}
354 
355 	/**
356 	 * Create a new file descriptor set. If @controllable, it
357 	 * is possible to restart or flush a call to gst_poll_wait() with
358 	 * gst_poll_restart() and gst_poll_set_flushing() respectively.
359 	 *
360 	 * Free-function: gst_poll_free
361 	 *
362 	 * Params:
363 	 *     controllable = whether it should be possible to control a wait.
364 	 *
365 	 * Returns: a new #GstPoll, or %NULL in
366 	 *     case of an error.  Free with gst_poll_free().
367 	 *
368 	 * Throws: ConstructionException GTK+ fails to create the object.
369 	 */
370 	public this(bool controllable)
371 	{
372 		auto p = gst_poll_new(controllable);
373 
374 		if(p is null)
375 		{
376 			throw new ConstructionException("null returned by new");
377 		}
378 
379 		this(cast(GstPoll*) p);
380 	}
381 
382 	/**
383 	 * Create a new poll object that can be used for scheduling cancellable
384 	 * timeouts.
385 	 *
386 	 * A timeout is performed with gst_poll_wait(). Multiple timeouts can be
387 	 * performed from different threads.
388 	 *
389 	 * Free-function: gst_poll_free
390 	 *
391 	 * Returns: a new #GstPoll, or %NULL in
392 	 *     case of an error.  Free with gst_poll_free().
393 	 *
394 	 * Throws: ConstructionException GTK+ fails to create the object.
395 	 */
396 	public this()
397 	{
398 		auto p = gst_poll_new_timer();
399 
400 		if(p is null)
401 		{
402 			throw new ConstructionException("null returned by new_timer");
403 		}
404 
405 		this(cast(GstPoll*) p);
406 	}
407 }