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.DatagramBasedIF; 26 27 private import gio.Cancellable; 28 private import glib.ErrorG; 29 private import glib.GException; 30 private import glib.Source; 31 private 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 or 73 * connectionless. The interface does not cover connection establishment — use 74 * methods on the underlying type to establish a connection before sending and 75 * receiving data through the #GDatagramBased API. For connectionless socket 76 * types the target/source address is specified or received in each I/O 77 * operation. 78 * 79 * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. 80 * To use a #GDatagramBased concurrently from multiple threads, you must 81 * implement your own locking. 82 * 83 * Since: 2.48 84 */ 85 public interface DatagramBasedIF{ 86 /** Get the main Gtk struct */ 87 public GDatagramBased* getDatagramBasedStruct(); 88 89 /** the main Gtk struct as a void* */ 90 protected void* getStruct(); 91 92 93 /** 94 * Checks on the readiness of @datagram_based to perform operations. The 95 * operations specified in @condition are checked for and masked against the 96 * currently-satisfied conditions on @datagram_based. The result is returned. 97 * 98 * %G_IO_IN will be set in the return value if data is available to read with 99 * g_datagram_based_receive_messages(), or if the connection is closed remotely 100 * (EOS); and if the datagram_based has not been closed locally using some 101 * implementation-specific method (such as g_socket_close() or 102 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). 103 * 104 * If the connection is shut down or closed (by calling g_socket_close() or 105 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for 106 * example), all calls to this function will return %G_IO_ERROR_CLOSED. 107 * 108 * %G_IO_OUT will be set if it is expected that at least one byte can be sent 109 * using g_datagram_based_send_messages() without blocking. It will not be set 110 * if the datagram_based has been closed locally. 111 * 112 * %G_IO_HUP will be set if the connection has been closed locally. 113 * 114 * %G_IO_ERR will be set if there was an asynchronous error in transmitting data 115 * previously enqueued using g_datagram_based_send_messages(). 116 * 117 * Note that on Windows, it is possible for an operation to return 118 * %G_IO_ERROR_WOULD_BLOCK even immediately after 119 * g_datagram_based_condition_check() has claimed that the #GDatagramBased is 120 * ready for writing. Rather than calling g_datagram_based_condition_check() and 121 * then writing to the #GDatagramBased if it succeeds, it is generally better to 122 * simply try writing right away, and try again later if the initial attempt 123 * returns %G_IO_ERROR_WOULD_BLOCK. 124 * 125 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these 126 * conditions will always be set in the output if they are true. Apart from 127 * these flags, the output is guaranteed to be masked by @condition. 128 * 129 * This call never blocks. 130 * 131 * Params: 132 * condition = a #GIOCondition mask to check 133 * 134 * Return: the #GIOCondition mask of the current state 135 * 136 * Since: 2.48 137 */ 138 public GIOCondition conditionCheck(GIOCondition condition); 139 140 /** 141 * Waits for up to @timeout microseconds for condition to become true on 142 * @datagram_based. If the condition is met, %TRUE is returned. 143 * 144 * If @cancellable is cancelled before the condition is met, or if @timeout is 145 * reached before the condition is met, then %FALSE is returned and @error is 146 * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). 147 * 148 * Params: 149 * condition = a #GIOCondition mask to wait for 150 * timeout = the maximum time (in microseconds) to wait, 0 to not block, or -1 151 * to block indefinitely 152 * cancellable = a #GCancellable 153 * 154 * Return: %TRUE if the condition was met, %FALSE otherwise 155 * 156 * Since: 2.48 157 * 158 * Throws: GException on failure. 159 */ 160 public bool conditionWait(GIOCondition condition, long timeout, Cancellable cancellable); 161 162 /** 163 * Creates a #GSource that can be attached to a #GMainContext to monitor for 164 * the availability of the specified @condition on the #GDatagramBased. The 165 * #GSource keeps a reference to the @datagram_based. 166 * 167 * The callback on the source is of the #GDatagramBasedSourceFunc type. 168 * 169 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these 170 * conditions will always be reported in the callback if they are true. 171 * 172 * If non-%NULL, @cancellable can be used to cancel the source, which will 173 * cause the source to trigger, reporting the current condition (which is 174 * likely 0 unless cancellation happened at the same time as a condition 175 * change). You can check for this in the callback using 176 * g_cancellable_is_cancelled(). 177 * 178 * Params: 179 * condition = a #GIOCondition mask to monitor 180 * cancellable = a #GCancellable 181 * 182 * Return: a newly allocated #GSource 183 * 184 * Since: 2.48 185 */ 186 public Source createSource(GIOCondition condition, Cancellable cancellable); 187 188 /** 189 * Receive one or more data messages from @datagram_based in one go. 190 * 191 * @messages must point to an array of #GInputMessage structs and 192 * @num_messages must be the length of this array. Each #GInputMessage 193 * contains a pointer to an array of #GInputVector structs describing the 194 * buffers that the data received in each message will be written to. 195 * 196 * @flags modify how all messages are received. The commonly available 197 * arguments for this are available in the #GSocketMsgFlags enum, but the 198 * values there are the same as the system values, and the flags 199 * are passed in as-is, so you can pass in system-specific flags too. These 200 * flags affect the overall receive operation. Flags affecting individual 201 * messages are returned in #GInputMessage.flags. 202 * 203 * The other members of #GInputMessage are treated as described in its 204 * documentation. 205 * 206 * If @timeout is negative the call will block until @num_messages have been 207 * received, the connection is closed remotely (EOS), @cancellable is cancelled, 208 * or an error occurs. 209 * 210 * If @timeout is 0 the call will return up to @num_messages without blocking, 211 * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system 212 * to be received. 213 * 214 * If @timeout is positive the call will block on the same conditions as if 215 * @timeout were negative. If the timeout is reached 216 * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, 217 * otherwise it will return the number of messages received before timing out. 218 * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with 219 * recvmmsg().) 220 * 221 * To be notified when messages are available, wait for the %G_IO_IN condition. 222 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from 223 * g_datagram_based_receive_messages() even if you were previously notified of a 224 * %G_IO_IN condition. 225 * 226 * If the remote peer closes the connection, any messages queued in the 227 * underlying receive buffer will be returned, and subsequent calls to 228 * g_datagram_based_receive_messages() will return 0 (with no error set). 229 * 230 * If the connection is shut down or closed (by calling g_socket_close() or 231 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for 232 * example), all calls to this function will return %G_IO_ERROR_CLOSED. 233 * 234 * On error -1 is returned and @error is set accordingly. An error will only 235 * be returned if zero messages could be received; otherwise the number of 236 * messages successfully received before the error will be returned. If 237 * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any 238 * other error. 239 * 240 * Params: 241 * messages = an array of #GInputMessage structs 242 * numMessages = the number of elements in @messages 243 * flags = an int containing #GSocketMsgFlags flags for the overall operation 244 * timeout = the maximum time (in microseconds) to wait, 0 to not block, or -1 245 * to block indefinitely 246 * cancellable = a %GCancellable 247 * 248 * Return: number of messages received, or -1 on error. Note that the number 249 * of messages received may be smaller than @num_messages if @timeout is 250 * zero or positive, if the peer closed the connection, or if @num_messages 251 * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try 252 * to receive the remaining messages. 253 * 254 * Since: 2.48 255 * 256 * Throws: GException on failure. 257 */ 258 public int receiveMessages(GInputMessage[] messages, int flags, long timeout, Cancellable cancellable); 259 260 /** 261 * Send one or more data messages from @datagram_based in one go. 262 * 263 * @messages must point to an array of #GOutputMessage structs and 264 * @num_messages must be the length of this array. Each #GOutputMessage 265 * contains an address to send the data to, and a pointer to an array of 266 * #GOutputVector structs to describe the buffers that the data to be sent 267 * for each message will be gathered from. 268 * 269 * @flags modify how the message is sent. The commonly available arguments 270 * for this are available in the #GSocketMsgFlags enum, but the 271 * values there are the same as the system values, and the flags 272 * are passed in as-is, so you can pass in system-specific flags too. 273 * 274 * The other members of #GOutputMessage are treated as described in its 275 * documentation. 276 * 277 * If @timeout is negative the call will block until @num_messages have been 278 * sent, @cancellable is cancelled, or an error occurs. 279 * 280 * If @timeout is 0 the call will send up to @num_messages without blocking, 281 * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. 282 * 283 * If @timeout is positive the call will block on the same conditions as if 284 * @timeout were negative. If the timeout is reached before any messages are 285 * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number 286 * of messages sent before timing out. 287 * 288 * To be notified when messages can be sent, wait for the %G_IO_OUT condition. 289 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from 290 * g_datagram_based_send_messages() even if you were previously notified of a 291 * %G_IO_OUT condition. (On Windows in particular, this is very common due to 292 * the way the underlying APIs work.) 293 * 294 * If the connection is shut down or closed (by calling g_socket_close() or 295 * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for 296 * example), all calls to this function will return %G_IO_ERROR_CLOSED. 297 * 298 * On error -1 is returned and @error is set accordingly. An error will only 299 * be returned if zero messages could be sent; otherwise the number of messages 300 * successfully sent before the error will be returned. If @cancellable is 301 * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. 302 * 303 * Params: 304 * messages = an array of #GOutputMessage structs 305 * numMessages = the number of elements in @messages 306 * flags = an int containing #GSocketMsgFlags flags 307 * timeout = the maximum time (in microseconds) to wait, 0 to not block, or -1 308 * to block indefinitely 309 * cancellable = a %GCancellable 310 * 311 * Return: number of messages sent, or -1 on error. Note that the number of 312 * messages sent may be smaller than @num_messages if @timeout is zero 313 * or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in 314 * which case the caller may re-try to send the remaining messages. 315 * 316 * Since: 2.48 317 * 318 * Throws: GException on failure. 319 */ 320 public int sendMessages(GOutputMessage[] messages, int flags, long timeout, Cancellable cancellable); 321 }