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 gio.DatagramBasedT;
26 
27 public  import gio.Cancellable;
28 public  import glib.ErrorG;
29 public  import glib.GException;
30 public  import glib.Source;
31 public  import gtkc.gio;
32 public  import gtkc.giotypes;
33 
34 
35 /**
36  * A #GDatagramBased is a networking interface for representing datagram-based
37  * communications. It is a more or less direct mapping of the core parts of the
38  * BSD socket API in a portable GObject interface. It is implemented by
39  * #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
40  * 
41  * #GDatagramBased is entirely platform independent, and is intended to be used
42  * alongside higher-level networking APIs such as #GIOStream.
43  * 
44  * It uses vectored scatter/gather I/O by default, allowing for many messages
45  * to be sent or received in a single call. Where possible, implementations of
46  * the interface should take advantage of vectored I/O to minimise processing
47  * or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
48  * possible. Callers should take advantage of scatter/gather I/O (the use of
49  * multiple buffers per message) to avoid unnecessary copying of data to
50  * assemble or disassemble a message.
51  * 
52  * Each #GDatagramBased operation has a timeout parameter which may be negative
53  * for blocking behaviour, zero for non-blocking behaviour, or positive for
54  * timeout behaviour. A blocking operation blocks until finished or there is an
55  * error. A non-blocking operation will return immediately with a
56  * %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
57  * will block until the operation is complete or the timeout expires; if the
58  * timeout expires it will return what progress it made, or
59  * %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
60  * successfully run you can call g_datagram_based_condition_check() or
61  * g_datagram_based_condition_wait(). You can also use
62  * g_datagram_based_create_source() and attach it to a #GMainContext to get
63  * callbacks when I/O is possible.
64  * 
65  * When running a non-blocking operation applications should always be able to
66  * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function
67  * said that I/O was possible. This can easily happen in case of a race
68  * condition in the application, but it can also happen for other reasons. For
69  * instance, on Windows a socket is always seen as writable until a write
70  * returns %G_IO_ERROR_WOULD_BLOCK.
71  * 
72  * As with #GSocket, #GDatagramBaseds can be either connection oriented (for
73  * example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be
74  * datagram-based, not stream-based. The interface does not cover connection
75  * establishment — use methods on the underlying type to establish a connection
76  * before sending and receiving data through the #GDatagramBased API. For
77  * connectionless socket types the target/source address is specified or
78  * received in each I/O operation.
79  * 
80  * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
81  * To use a #GDatagramBased concurrently from multiple threads, you must
82  * implement your own locking.
83  *
84  * Since: 2.48
85  */
86 public template DatagramBasedT(TStruct)
87 {
88 	/** Get the main Gtk struct */
89 	public GDatagramBased* getDatagramBasedStruct(bool transferOwnership = false)
90 	{
91 		if (transferOwnership)
92 			ownedRef = false;
93 		return cast(GDatagramBased*)getStruct();
94 	}
95 
96 
97 	/**
98 	 * Checks on the readiness of @datagram_based to perform operations. The
99 	 * operations specified in @condition are checked for and masked against the
100 	 * currently-satisfied conditions on @datagram_based. The result is returned.
101 	 *
102 	 * %G_IO_IN will be set in the return value if data is available to read with
103 	 * g_datagram_based_receive_messages(), or if the connection is closed remotely
104 	 * (EOS); and if the datagram_based has not been closed locally using some
105 	 * implementation-specific method (such as g_socket_close() or
106 	 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
107 	 *
108 	 * If the connection is shut down or closed (by calling g_socket_close() or
109 	 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
110 	 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
111 	 *
112 	 * %G_IO_OUT will be set if it is expected that at least one byte can be sent
113 	 * using g_datagram_based_send_messages() without blocking. It will not be set
114 	 * if the datagram_based has been closed locally.
115 	 *
116 	 * %G_IO_HUP will be set if the connection has been closed locally.
117 	 *
118 	 * %G_IO_ERR will be set if there was an asynchronous error in transmitting data
119 	 * previously enqueued using g_datagram_based_send_messages().
120 	 *
121 	 * Note that on Windows, it is possible for an operation to return
122 	 * %G_IO_ERROR_WOULD_BLOCK even immediately after
123 	 * g_datagram_based_condition_check() has claimed that the #GDatagramBased is
124 	 * ready for writing. Rather than calling g_datagram_based_condition_check() and
125 	 * then writing to the #GDatagramBased if it succeeds, it is generally better to
126 	 * simply try writing right away, and try again later if the initial attempt
127 	 * returns %G_IO_ERROR_WOULD_BLOCK.
128 	 *
129 	 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
130 	 * conditions will always be set in the output if they are true. Apart from
131 	 * these flags, the output is guaranteed to be masked by @condition.
132 	 *
133 	 * This call never blocks.
134 	 *
135 	 * Params:
136 	 *     condition = a #GIOCondition mask to check
137 	 *
138 	 * Returns: the #GIOCondition mask of the current state
139 	 *
140 	 * Since: 2.48
141 	 */
142 	public GIOCondition conditionCheck(GIOCondition condition)
143 	{
144 		return g_datagram_based_condition_check(getDatagramBasedStruct(), condition);
145 	}
146 
147 	/**
148 	 * Waits for up to @timeout microseconds for condition to become true on
149 	 * @datagram_based. If the condition is met, %TRUE is returned.
150 	 *
151 	 * If @cancellable is cancelled before the condition is met, or if @timeout is
152 	 * reached before the condition is met, then %FALSE is returned and @error is
153 	 * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
154 	 *
155 	 * Params:
156 	 *     condition = a #GIOCondition mask to wait for
157 	 *     timeout = the maximum time (in microseconds) to wait, 0 to not block, or -1
158 	 *         to block indefinitely
159 	 *     cancellable = a #GCancellable
160 	 *
161 	 * Returns: %TRUE if the condition was met, %FALSE otherwise
162 	 *
163 	 * Since: 2.48
164 	 *
165 	 * Throws: GException on failure.
166 	 */
167 	public bool conditionWait(GIOCondition condition, long timeout, Cancellable cancellable)
168 	{
169 		GError* err = null;
170 		
171 		auto p = g_datagram_based_condition_wait(getDatagramBasedStruct(), condition, timeout, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
172 		
173 		if (err !is null)
174 		{
175 			throw new GException( new ErrorG(err) );
176 		}
177 		
178 		return p;
179 	}
180 
181 	/**
182 	 * Creates a #GSource that can be attached to a #GMainContext to monitor for
183 	 * the availability of the specified @condition on the #GDatagramBased. The
184 	 * #GSource keeps a reference to the @datagram_based.
185 	 *
186 	 * The callback on the source is of the #GDatagramBasedSourceFunc type.
187 	 *
188 	 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
189 	 * conditions will always be reported in the callback if they are true.
190 	 *
191 	 * If non-%NULL, @cancellable can be used to cancel the source, which will
192 	 * cause the source to trigger, reporting the current condition (which is
193 	 * likely 0 unless cancellation happened at the same time as a condition
194 	 * change). You can check for this in the callback using
195 	 * g_cancellable_is_cancelled().
196 	 *
197 	 * Params:
198 	 *     condition = a #GIOCondition mask to monitor
199 	 *     cancellable = a #GCancellable
200 	 *
201 	 * Returns: a newly allocated #GSource
202 	 *
203 	 * Since: 2.48
204 	 */
205 	public Source createSource(GIOCondition condition, Cancellable cancellable)
206 	{
207 		auto p = g_datagram_based_create_source(getDatagramBasedStruct(), condition, (cancellable is null) ? null : cancellable.getCancellableStruct());
208 		
209 		if(p is null)
210 		{
211 			return null;
212 		}
213 		
214 		return new Source(cast(GSource*) p, true);
215 	}
216 
217 	/**
218 	 * Receive one or more data messages from @datagram_based in one go.
219 	 *
220 	 * @messages must point to an array of #GInputMessage structs and
221 	 * @num_messages must be the length of this array. Each #GInputMessage
222 	 * contains a pointer to an array of #GInputVector structs describing the
223 	 * buffers that the data received in each message will be written to.
224 	 *
225 	 * @flags modify how all messages are received. The commonly available
226 	 * arguments for this are available in the #GSocketMsgFlags enum, but the
227 	 * values there are the same as the system values, and the flags
228 	 * are passed in as-is, so you can pass in system-specific flags too. These
229 	 * flags affect the overall receive operation. Flags affecting individual
230 	 * messages are returned in #GInputMessage.flags.
231 	 *
232 	 * The other members of #GInputMessage are treated as described in its
233 	 * documentation.
234 	 *
235 	 * If @timeout is negative the call will block until @num_messages have been
236 	 * received, the connection is closed remotely (EOS), @cancellable is cancelled,
237 	 * or an error occurs.
238 	 *
239 	 * If @timeout is 0 the call will return up to @num_messages without blocking,
240 	 * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
241 	 * to be received.
242 	 *
243 	 * If @timeout is positive the call will block on the same conditions as if
244 	 * @timeout were negative. If the timeout is reached
245 	 * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
246 	 * otherwise it will return the number of messages received before timing out.
247 	 * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
248 	 * recvmmsg().)
249 	 *
250 	 * To be notified when messages are available, wait for the %G_IO_IN condition.
251 	 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
252 	 * g_datagram_based_receive_messages() even if you were previously notified of a
253 	 * %G_IO_IN condition.
254 	 *
255 	 * If the remote peer closes the connection, any messages queued in the
256 	 * underlying receive buffer will be returned, and subsequent calls to
257 	 * g_datagram_based_receive_messages() will return 0 (with no error set).
258 	 *
259 	 * If the connection is shut down or closed (by calling g_socket_close() or
260 	 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
261 	 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
262 	 *
263 	 * On error -1 is returned and @error is set accordingly. An error will only
264 	 * be returned if zero messages could be received; otherwise the number of
265 	 * messages successfully received before the error will be returned. If
266 	 * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
267 	 * other error.
268 	 *
269 	 * Params:
270 	 *     messages = an array of #GInputMessage structs
271 	 *     numMessages = the number of elements in @messages
272 	 *     flags = an int containing #GSocketMsgFlags flags for the overall operation
273 	 *     timeout = the maximum time (in microseconds) to wait, 0 to not block, or -1
274 	 *         to block indefinitely
275 	 *     cancellable = a %GCancellable
276 	 *
277 	 * Returns: number of messages received, or -1 on error. Note that the number
278 	 *     of messages received may be smaller than @num_messages if @timeout is
279 	 *     zero or positive, if the peer closed the connection, or if @num_messages
280 	 *     was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
281 	 *     to receive the remaining messages.
282 	 *
283 	 * Since: 2.48
284 	 *
285 	 * Throws: GException on failure.
286 	 */
287 	public int receiveMessages(GInputMessage[] messages, int flags, long timeout, Cancellable cancellable)
288 	{
289 		GError* err = null;
290 		
291 		auto p = g_datagram_based_receive_messages(getDatagramBasedStruct(), messages.ptr, cast(uint)messages.length, flags, timeout, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
292 		
293 		if (err !is null)
294 		{
295 			throw new GException( new ErrorG(err) );
296 		}
297 		
298 		return p;
299 	}
300 
301 	/**
302 	 * Send one or more data messages from @datagram_based in one go.
303 	 *
304 	 * @messages must point to an array of #GOutputMessage structs and
305 	 * @num_messages must be the length of this array. Each #GOutputMessage
306 	 * contains an address to send the data to, and a pointer to an array of
307 	 * #GOutputVector structs to describe the buffers that the data to be sent
308 	 * for each message will be gathered from.
309 	 *
310 	 * @flags modify how the message is sent. The commonly available arguments
311 	 * for this are available in the #GSocketMsgFlags enum, but the
312 	 * values there are the same as the system values, and the flags
313 	 * are passed in as-is, so you can pass in system-specific flags too.
314 	 *
315 	 * The other members of #GOutputMessage are treated as described in its
316 	 * documentation.
317 	 *
318 	 * If @timeout is negative the call will block until @num_messages have been
319 	 * sent, @cancellable is cancelled, or an error occurs.
320 	 *
321 	 * If @timeout is 0 the call will send up to @num_messages without blocking,
322 	 * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
323 	 *
324 	 * If @timeout is positive the call will block on the same conditions as if
325 	 * @timeout were negative. If the timeout is reached before any messages are
326 	 * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
327 	 * of messages sent before timing out.
328 	 *
329 	 * To be notified when messages can be sent, wait for the %G_IO_OUT condition.
330 	 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
331 	 * g_datagram_based_send_messages() even if you were previously notified of a
332 	 * %G_IO_OUT condition. (On Windows in particular, this is very common due to
333 	 * the way the underlying APIs work.)
334 	 *
335 	 * If the connection is shut down or closed (by calling g_socket_close() or
336 	 * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
337 	 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
338 	 *
339 	 * On error -1 is returned and @error is set accordingly. An error will only
340 	 * be returned if zero messages could be sent; otherwise the number of messages
341 	 * successfully sent before the error will be returned. If @cancellable is
342 	 * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
343 	 *
344 	 * Params:
345 	 *     messages = an array of #GOutputMessage structs
346 	 *     numMessages = the number of elements in @messages
347 	 *     flags = an int containing #GSocketMsgFlags flags
348 	 *     timeout = the maximum time (in microseconds) to wait, 0 to not block, or -1
349 	 *         to block indefinitely
350 	 *     cancellable = a %GCancellable
351 	 *
352 	 * Returns: number of messages sent, or -1 on error. Note that the number of
353 	 *     messages sent may be smaller than @num_messages if @timeout is zero
354 	 *     or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
355 	 *     which case the caller may re-try to send the remaining messages.
356 	 *
357 	 * Since: 2.48
358 	 *
359 	 * Throws: GException on failure.
360 	 */
361 	public int sendMessages(GOutputMessage[] messages, int flags, long timeout, Cancellable cancellable)
362 	{
363 		GError* err = null;
364 		
365 		auto p = g_datagram_based_send_messages(getDatagramBasedStruct(), messages.ptr, cast(uint)messages.length, flags, timeout, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
366 		
367 		if (err !is null)
368 		{
369 			throw new GException( new ErrorG(err) );
370 		}
371 		
372 		return p;
373 	}
374 }