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.Socket; 26 27 private import gio.Cancellable; 28 private import gio.Credentials; 29 private import gio.DatagramBasedIF; 30 private import gio.DatagramBasedT; 31 private import gio.InetAddress; 32 private import gio.InitableIF; 33 private import gio.InitableT; 34 private import gio.SocketAddress; 35 private import gio.SocketConnection; 36 private import gio.SocketControlMessage; 37 private import glib.ConstructionException; 38 private import glib.ErrorG; 39 private import glib.GException; 40 private import glib.Source; 41 private import glib.Str; 42 private import gobject.ObjectG; 43 private import gtkc.gio; 44 public import gtkc.giotypes; 45 46 47 /** 48 * A #GSocket is a low-level networking primitive. It is a more or less 49 * direct mapping of the BSD socket API in a portable GObject based API. 50 * It supports both the UNIX socket implementations and winsock2 on Windows. 51 * 52 * #GSocket is the platform independent base upon which the higher level 53 * network primitives are based. Applications are not typically meant to 54 * use it directly, but rather through classes like #GSocketClient, 55 * #GSocketService and #GSocketConnection. However there may be cases where 56 * direct use of #GSocket is useful. 57 * 58 * #GSocket implements the #GInitable interface, so if it is manually constructed 59 * by e.g. g_object_new() you must call g_initable_init() and check the 60 * results before using the object. This is done automatically in 61 * g_socket_new() and g_socket_new_from_fd(), so these functions can return 62 * %NULL. 63 * 64 * Sockets operate in two general modes, blocking or non-blocking. When 65 * in blocking mode all operations (which don’t take an explicit blocking 66 * parameter) block until the requested operation 67 * is finished or there is an error. In non-blocking mode all calls that 68 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. 69 * To know when a call would successfully run you can call g_socket_condition_check(), 70 * or g_socket_condition_wait(). You can also use g_socket_create_source() and 71 * attach it to a #GMainContext to get callbacks when I/O is possible. 72 * Note that all sockets are always set to non blocking mode in the system, and 73 * blocking mode is emulated in GSocket. 74 * 75 * When working in non-blocking mode applications should always be able to 76 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other 77 * function said that I/O was possible. This can easily happen in case 78 * of a race condition in the application, but it can also happen for other 79 * reasons. For instance, on Windows a socket is always seen as writable 80 * until a write returns %G_IO_ERROR_WOULD_BLOCK. 81 * 82 * #GSockets can be either connection oriented or datagram based. 83 * For connection oriented types you must first establish a connection by 84 * either connecting to an address or accepting a connection from another 85 * address. For connectionless socket types the target/source address is 86 * specified or received in each I/O operation. 87 * 88 * All socket file descriptors are set to be close-on-exec. 89 * 90 * Note that creating a #GSocket causes the signal %SIGPIPE to be 91 * ignored for the remainder of the program. If you are writing a 92 * command-line utility that uses #GSocket, you may need to take into 93 * account the fact that your program will not automatically be killed 94 * if it tries to write to %stdout after it has been closed. 95 * 96 * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use 97 * a #GSocket concurrently from multiple threads, you must implement your own 98 * locking. 99 * 100 * Since: 2.22 101 */ 102 public class Socket : ObjectG, DatagramBasedIF, InitableIF 103 { 104 /** the main Gtk struct */ 105 protected GSocket* gSocket; 106 107 /** Get the main Gtk struct */ 108 public GSocket* getSocketStruct(bool transferOwnership = false) 109 { 110 if (transferOwnership) 111 ownedRef = false; 112 return gSocket; 113 } 114 115 /** the main Gtk struct as a void* */ 116 protected override void* getStruct() 117 { 118 return cast(void*)gSocket; 119 } 120 121 protected override void setStruct(GObject* obj) 122 { 123 gSocket = cast(GSocket*)obj; 124 super.setStruct(obj); 125 } 126 127 /** 128 * Sets our main struct and passes it to the parent class. 129 */ 130 public this (GSocket* gSocket, bool ownedRef = false) 131 { 132 this.gSocket = gSocket; 133 super(cast(GObject*)gSocket, ownedRef); 134 } 135 136 // add the DatagramBased capabilities 137 mixin DatagramBasedT!(GSocket); 138 139 // add the Initable capabilities 140 mixin InitableT!(GSocket); 141 142 143 /** */ 144 public static GType getType() 145 { 146 return g_socket_get_type(); 147 } 148 149 /** 150 * Creates a new #GSocket with the defined family, type and protocol. 151 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type 152 * for the family and type is used. 153 * 154 * The @protocol is a family and type specific int that specifies what 155 * kind of protocol to use. #GSocketProtocol lists several common ones. 156 * Many families only support one protocol, and use 0 for this, others 157 * support several and using 0 means to use the default protocol for 158 * the family and type. 159 * 160 * The protocol id is passed directly to the operating 161 * system, so you can use protocols not listed in #GSocketProtocol if you 162 * know the protocol number used for it. 163 * 164 * Params: 165 * family = the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. 166 * type = the socket type to use. 167 * protocol = the id of the protocol to use, or 0 for default. 168 * 169 * Returns: a #GSocket or %NULL on error. 170 * Free the returned object with g_object_unref(). 171 * 172 * Since: 2.22 173 * 174 * Throws: GException on failure. 175 * Throws: ConstructionException GTK+ fails to create the object. 176 */ 177 public this(GSocketFamily family, GSocketType type, GSocketProtocol protocol) 178 { 179 GError* err = null; 180 181 auto p = g_socket_new(family, type, protocol, &err); 182 183 if (err !is null) 184 { 185 throw new GException( new ErrorG(err) ); 186 } 187 188 if(p is null) 189 { 190 throw new ConstructionException("null returned by new"); 191 } 192 193 this(cast(GSocket*) p, true); 194 } 195 196 /** 197 * Creates a new #GSocket from a native file descriptor 198 * or winsock SOCKET handle. 199 * 200 * This reads all the settings from the file descriptor so that 201 * all properties should work. Note that the file descriptor 202 * will be set to non-blocking mode, independent on the blocking 203 * mode of the #GSocket. 204 * 205 * On success, the returned #GSocket takes ownership of @fd. On failure, the 206 * caller must close @fd themselves. 207 * 208 * Since GLib 2.46, it is no longer a fatal error to call this on a non-socket 209 * descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED 210 * 211 * Params: 212 * fd = a native socket file descriptor. 213 * 214 * Returns: a #GSocket or %NULL on error. 215 * Free the returned object with g_object_unref(). 216 * 217 * Since: 2.22 218 * 219 * Throws: GException on failure. 220 * Throws: ConstructionException GTK+ fails to create the object. 221 */ 222 public this(int fd) 223 { 224 GError* err = null; 225 226 auto p = g_socket_new_from_fd(fd, &err); 227 228 if (err !is null) 229 { 230 throw new GException( new ErrorG(err) ); 231 } 232 233 if(p is null) 234 { 235 throw new ConstructionException("null returned by new_from_fd"); 236 } 237 238 this(cast(GSocket*) p, true); 239 } 240 241 /** 242 * Accept incoming connections on a connection-based socket. This removes 243 * the first outstanding connection request from the listening socket and 244 * creates a #GSocket object for it. 245 * 246 * The @socket must be bound to a local address with g_socket_bind() and 247 * must be listening for incoming connections (g_socket_listen()). 248 * 249 * If there are no outstanding connections then the operation will block 250 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. 251 * To be notified of an incoming connection, wait for the %G_IO_IN condition. 252 * 253 * Params: 254 * cancellable = a %GCancellable or %NULL 255 * 256 * Returns: a new #GSocket, or %NULL on error. 257 * Free the returned object with g_object_unref(). 258 * 259 * Since: 2.22 260 * 261 * Throws: GException on failure. 262 */ 263 public Socket accept(Cancellable cancellable) 264 { 265 GError* err = null; 266 267 auto p = g_socket_accept(gSocket, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 268 269 if (err !is null) 270 { 271 throw new GException( new ErrorG(err) ); 272 } 273 274 if(p is null) 275 { 276 return null; 277 } 278 279 return ObjectG.getDObject!(Socket)(cast(GSocket*) p, true); 280 } 281 282 /** 283 * When a socket is created it is attached to an address family, but it 284 * doesn't have an address in this family. g_socket_bind() assigns the 285 * address (sometimes called name) of the socket. 286 * 287 * It is generally required to bind to a local address before you can 288 * receive connections. (See g_socket_listen() and g_socket_accept() ). 289 * In certain situations, you may also want to bind a socket that will be 290 * used to initiate connections, though this is not normally required. 291 * 292 * If @socket is a TCP socket, then @allow_reuse controls the setting 293 * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for 294 * server sockets (sockets that you will eventually call 295 * g_socket_accept() on), and %FALSE for client sockets. (Failing to 296 * set this flag on a server socket may cause g_socket_bind() to return 297 * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then 298 * immediately restarted.) 299 * 300 * If @socket is a UDP socket, then @allow_reuse determines whether or 301 * not other UDP sockets can be bound to the same address at the same 302 * time. In particular, you can have several UDP sockets bound to the 303 * same address, and they will all receive all of the multicast and 304 * broadcast packets sent to that address. (The behavior of unicast 305 * UDP packets to an address with multiple listeners is not defined.) 306 * 307 * Params: 308 * address = a #GSocketAddress specifying the local address. 309 * allowReuse = whether to allow reusing this address 310 * 311 * Returns: %TRUE on success, %FALSE on error. 312 * 313 * Since: 2.22 314 * 315 * Throws: GException on failure. 316 */ 317 public bool bind(SocketAddress address, bool allowReuse) 318 { 319 GError* err = null; 320 321 auto p = g_socket_bind(gSocket, (address is null) ? null : address.getSocketAddressStruct(), allowReuse, &err) != 0; 322 323 if (err !is null) 324 { 325 throw new GException( new ErrorG(err) ); 326 } 327 328 return p; 329 } 330 331 /** 332 * Checks and resets the pending connect error for the socket. 333 * This is used to check for errors when g_socket_connect() is 334 * used in non-blocking mode. 335 * 336 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error 337 * 338 * Since: 2.22 339 * 340 * Throws: GException on failure. 341 */ 342 public bool checkConnectResult() 343 { 344 GError* err = null; 345 346 auto p = g_socket_check_connect_result(gSocket, &err) != 0; 347 348 if (err !is null) 349 { 350 throw new GException( new ErrorG(err) ); 351 } 352 353 return p; 354 } 355 356 /** 357 * Closes the socket, shutting down any active connection. 358 * 359 * Closing a socket does not wait for all outstanding I/O operations 360 * to finish, so the caller should not rely on them to be guaranteed 361 * to complete even if the close returns with no error. 362 * 363 * Once the socket is closed, all other operations will return 364 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not 365 * return an error. 366 * 367 * Sockets will be automatically closed when the last reference 368 * is dropped, but you might want to call this function to make sure 369 * resources are released as early as possible. 370 * 371 * Beware that due to the way that TCP works, it is possible for 372 * recently-sent data to be lost if either you close a socket while the 373 * %G_IO_IN condition is set, or else if the remote connection tries to 374 * send something to you after you close the socket but before it has 375 * finished reading all of the data you sent. There is no easy generic 376 * way to avoid this problem; the easiest fix is to design the network 377 * protocol such that the client will never send data "out of turn". 378 * Another solution is for the server to half-close the connection by 379 * calling g_socket_shutdown() with only the @shutdown_write flag set, 380 * and then wait for the client to notice this and close its side of the 381 * connection, after which the server can safely call g_socket_close(). 382 * (This is what #GTcpConnection does if you call 383 * g_tcp_connection_set_graceful_disconnect(). But of course, this 384 * only works if the client will close its connection after the server 385 * does.) 386 * 387 * Returns: %TRUE on success, %FALSE on error 388 * 389 * Since: 2.22 390 * 391 * Throws: GException on failure. 392 */ 393 public bool close() 394 { 395 GError* err = null; 396 397 auto p = g_socket_close(gSocket, &err) != 0; 398 399 if (err !is null) 400 { 401 throw new GException( new ErrorG(err) ); 402 } 403 404 return p; 405 } 406 407 /** 408 * Checks on the readiness of @socket to perform operations. 409 * The operations specified in @condition are checked for and masked 410 * against the currently-satisfied conditions on @socket. The result 411 * is returned. 412 * 413 * Note that on Windows, it is possible for an operation to return 414 * %G_IO_ERROR_WOULD_BLOCK even immediately after 415 * g_socket_condition_check() has claimed that the socket is ready for 416 * writing. Rather than calling g_socket_condition_check() and then 417 * writing to the socket if it succeeds, it is generally better to 418 * simply try writing to the socket right away, and try again later if 419 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. 420 * 421 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; 422 * these conditions will always be set in the output if they are true. 423 * 424 * This call never blocks. 425 * 426 * Params: 427 * condition = a #GIOCondition mask to check 428 * 429 * Returns: the @GIOCondition mask of the current state 430 * 431 * Since: 2.22 432 */ 433 public GIOCondition conditionCheck(GIOCondition condition) 434 { 435 return g_socket_condition_check(gSocket, condition); 436 } 437 438 /** 439 * Waits for up to @timeout microseconds for @condition to become true 440 * on @socket. If the condition is met, %TRUE is returned. 441 * 442 * If @cancellable is cancelled before the condition is met, or if 443 * @timeout (or the socket's #GSocket:timeout) is reached before the 444 * condition is met, then %FALSE is returned and @error, if non-%NULL, 445 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or 446 * %G_IO_ERROR_TIMED_OUT). 447 * 448 * If you don't want a timeout, use g_socket_condition_wait(). 449 * (Alternatively, you can pass -1 for @timeout.) 450 * 451 * Note that although @timeout is in microseconds for consistency with 452 * other GLib APIs, this function actually only has millisecond 453 * resolution, and the behavior is undefined if @timeout is not an 454 * exact number of milliseconds. 455 * 456 * Params: 457 * condition = a #GIOCondition mask to wait for 458 * timeout = the maximum time (in microseconds) to wait, or -1 459 * cancellable = a #GCancellable, or %NULL 460 * 461 * Returns: %TRUE if the condition was met, %FALSE otherwise 462 * 463 * Since: 2.32 464 * 465 * Throws: GException on failure. 466 */ 467 public bool conditionTimedWait(GIOCondition condition, long timeout, Cancellable cancellable) 468 { 469 GError* err = null; 470 471 auto p = g_socket_condition_timed_wait(gSocket, condition, timeout, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0; 472 473 if (err !is null) 474 { 475 throw new GException( new ErrorG(err) ); 476 } 477 478 return p; 479 } 480 481 /** 482 * Waits for @condition to become true on @socket. When the condition 483 * is met, %TRUE is returned. 484 * 485 * If @cancellable is cancelled before the condition is met, or if the 486 * socket has a timeout set and it is reached before the condition is 487 * met, then %FALSE is returned and @error, if non-%NULL, is set to 488 * the appropriate value (%G_IO_ERROR_CANCELLED or 489 * %G_IO_ERROR_TIMED_OUT). 490 * 491 * See also g_socket_condition_timed_wait(). 492 * 493 * Params: 494 * condition = a #GIOCondition mask to wait for 495 * cancellable = a #GCancellable, or %NULL 496 * 497 * Returns: %TRUE if the condition was met, %FALSE otherwise 498 * 499 * Since: 2.22 500 * 501 * Throws: GException on failure. 502 */ 503 public bool conditionWait(GIOCondition condition, Cancellable cancellable) 504 { 505 GError* err = null; 506 507 auto p = g_socket_condition_wait(gSocket, condition, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0; 508 509 if (err !is null) 510 { 511 throw new GException( new ErrorG(err) ); 512 } 513 514 return p; 515 } 516 517 /** 518 * Connect the socket to the specified remote address. 519 * 520 * For connection oriented socket this generally means we attempt to make 521 * a connection to the @address. For a connection-less socket it sets 522 * the default address for g_socket_send() and discards all incoming datagrams 523 * from other sources. 524 * 525 * Generally connection oriented sockets can only connect once, but 526 * connection-less sockets can connect multiple times to change the 527 * default address. 528 * 529 * If the connect call needs to do network I/O it will block, unless 530 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned 531 * and the user can be notified of the connection finishing by waiting 532 * for the G_IO_OUT condition. The result of the connection must then be 533 * checked with g_socket_check_connect_result(). 534 * 535 * Params: 536 * address = a #GSocketAddress specifying the remote address. 537 * cancellable = a %GCancellable or %NULL 538 * 539 * Returns: %TRUE if connected, %FALSE on error. 540 * 541 * Since: 2.22 542 * 543 * Throws: GException on failure. 544 */ 545 public bool connect(SocketAddress address, Cancellable cancellable) 546 { 547 GError* err = null; 548 549 auto p = g_socket_connect(gSocket, (address is null) ? null : address.getSocketAddressStruct(), (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0; 550 551 if (err !is null) 552 { 553 throw new GException( new ErrorG(err) ); 554 } 555 556 return p; 557 } 558 559 /** 560 * Creates a #GSocketConnection subclass of the right type for 561 * @socket. 562 * 563 * Returns: a #GSocketConnection 564 * 565 * Since: 2.22 566 */ 567 public SocketConnection connectionFactoryCreateConnection() 568 { 569 auto p = g_socket_connection_factory_create_connection(gSocket); 570 571 if(p is null) 572 { 573 return null; 574 } 575 576 return ObjectG.getDObject!(SocketConnection)(cast(GSocketConnection*) p, true); 577 } 578 579 /** 580 * Creates a #GSource that can be attached to a %GMainContext to monitor 581 * for the availability of the specified @condition on the socket. The #GSource 582 * keeps a reference to the @socket. 583 * 584 * The callback on the source is of the #GSocketSourceFunc type. 585 * 586 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; 587 * these conditions will always be reported output if they are true. 588 * 589 * @cancellable if not %NULL can be used to cancel the source, which will 590 * cause the source to trigger, reporting the current condition (which 591 * is likely 0 unless cancellation happened at the same time as a 592 * condition change). You can check for this in the callback using 593 * g_cancellable_is_cancelled(). 594 * 595 * If @socket has a timeout set, and it is reached before @condition 596 * occurs, the source will then trigger anyway, reporting %G_IO_IN or 597 * %G_IO_OUT depending on @condition. However, @socket will have been 598 * marked as having had a timeout, and so the next #GSocket I/O method 599 * you call will then fail with a %G_IO_ERROR_TIMED_OUT. 600 * 601 * Params: 602 * condition = a #GIOCondition mask to monitor 603 * cancellable = a %GCancellable or %NULL 604 * 605 * Returns: a newly allocated %GSource, free with g_source_unref(). 606 * 607 * Since: 2.22 608 */ 609 public Source createSource(GIOCondition condition, Cancellable cancellable) 610 { 611 auto p = g_socket_create_source(gSocket, condition, (cancellable is null) ? null : cancellable.getCancellableStruct()); 612 613 if(p is null) 614 { 615 return null; 616 } 617 618 return new Source(cast(GSource*) p, true); 619 } 620 621 /** 622 * Get the amount of data pending in the OS input buffer, without blocking. 623 * 624 * If @socket is a UDP or SCTP socket, this will return the size of 625 * just the next packet, even if additional packets are buffered after 626 * that one. 627 * 628 * Note that on Windows, this function is rather inefficient in the 629 * UDP case, and so if you know any plausible upper bound on the size 630 * of the incoming packet, it is better to just do a 631 * g_socket_receive() with a buffer of that size, rather than calling 632 * g_socket_get_available_bytes() first and then doing a receive of 633 * exactly the right size. 634 * 635 * Returns: the number of bytes that can be read from the socket 636 * without blocking or truncating, or -1 on error. 637 * 638 * Since: 2.32 639 */ 640 public ptrdiff_t getAvailableBytes() 641 { 642 return g_socket_get_available_bytes(gSocket); 643 } 644 645 /** 646 * Gets the blocking mode of the socket. For details on blocking I/O, 647 * see g_socket_set_blocking(). 648 * 649 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise. 650 * 651 * Since: 2.22 652 */ 653 public bool getBlocking() 654 { 655 return g_socket_get_blocking(gSocket) != 0; 656 } 657 658 /** 659 * Gets the broadcast setting on @socket; if %TRUE, 660 * it is possible to send packets to broadcast 661 * addresses. 662 * 663 * Returns: the broadcast setting on @socket 664 * 665 * Since: 2.32 666 */ 667 public bool getBroadcast() 668 { 669 return g_socket_get_broadcast(gSocket) != 0; 670 } 671 672 /** 673 * Returns the credentials of the foreign process connected to this 674 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX 675 * sockets). 676 * 677 * If this operation isn't supported on the OS, the method fails with 678 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented 679 * by reading the %SO_PEERCRED option on the underlying socket. 680 * 681 * Other ways to obtain credentials from a foreign peer includes the 682 * #GUnixCredentialsMessage type and 683 * g_unix_connection_send_credentials() / 684 * g_unix_connection_receive_credentials() functions. 685 * 686 * Returns: %NULL if @error is set, otherwise a #GCredentials object 687 * that must be freed with g_object_unref(). 688 * 689 * Since: 2.26 690 * 691 * Throws: GException on failure. 692 */ 693 public Credentials getCredentials() 694 { 695 GError* err = null; 696 697 auto p = g_socket_get_credentials(gSocket, &err); 698 699 if (err !is null) 700 { 701 throw new GException( new ErrorG(err) ); 702 } 703 704 if(p is null) 705 { 706 return null; 707 } 708 709 return ObjectG.getDObject!(Credentials)(cast(GCredentials*) p, true); 710 } 711 712 /** 713 * Gets the socket family of the socket. 714 * 715 * Returns: a #GSocketFamily 716 * 717 * Since: 2.22 718 */ 719 public GSocketFamily getFamily() 720 { 721 return g_socket_get_family(gSocket); 722 } 723 724 /** 725 * Returns the underlying OS socket object. On unix this 726 * is a socket file descriptor, and on Windows this is 727 * a Winsock2 SOCKET handle. This may be useful for 728 * doing platform specific or otherwise unusual operations 729 * on the socket. 730 * 731 * Returns: the file descriptor of the socket. 732 * 733 * Since: 2.22 734 */ 735 public int getFd() 736 { 737 return g_socket_get_fd(gSocket); 738 } 739 740 /** 741 * Gets the keepalive mode of the socket. For details on this, 742 * see g_socket_set_keepalive(). 743 * 744 * Returns: %TRUE if keepalive is active, %FALSE otherwise. 745 * 746 * Since: 2.22 747 */ 748 public bool getKeepalive() 749 { 750 return g_socket_get_keepalive(gSocket) != 0; 751 } 752 753 /** 754 * Gets the listen backlog setting of the socket. For details on this, 755 * see g_socket_set_listen_backlog(). 756 * 757 * Returns: the maximum number of pending connections. 758 * 759 * Since: 2.22 760 */ 761 public int getListenBacklog() 762 { 763 return g_socket_get_listen_backlog(gSocket); 764 } 765 766 /** 767 * Try to get the local address of a bound socket. This is only 768 * useful if the socket has been bound to a local address, 769 * either explicitly or implicitly when connecting. 770 * 771 * Returns: a #GSocketAddress or %NULL on error. 772 * Free the returned object with g_object_unref(). 773 * 774 * Since: 2.22 775 * 776 * Throws: GException on failure. 777 */ 778 public SocketAddress getLocalAddress() 779 { 780 GError* err = null; 781 782 auto p = g_socket_get_local_address(gSocket, &err); 783 784 if (err !is null) 785 { 786 throw new GException( new ErrorG(err) ); 787 } 788 789 if(p is null) 790 { 791 return null; 792 } 793 794 return ObjectG.getDObject!(SocketAddress)(cast(GSocketAddress*) p, true); 795 } 796 797 /** 798 * Gets the multicast loopback setting on @socket; if %TRUE (the 799 * default), outgoing multicast packets will be looped back to 800 * multicast listeners on the same host. 801 * 802 * Returns: the multicast loopback setting on @socket 803 * 804 * Since: 2.32 805 */ 806 public bool getMulticastLoopback() 807 { 808 return g_socket_get_multicast_loopback(gSocket) != 0; 809 } 810 811 /** 812 * Gets the multicast time-to-live setting on @socket; see 813 * g_socket_set_multicast_ttl() for more details. 814 * 815 * Returns: the multicast time-to-live setting on @socket 816 * 817 * Since: 2.32 818 */ 819 public uint getMulticastTtl() 820 { 821 return g_socket_get_multicast_ttl(gSocket); 822 } 823 824 /** 825 * Gets the value of an integer-valued option on @socket, as with 826 * getsockopt(). (If you need to fetch a non-integer-valued option, 827 * you will need to call getsockopt() directly.) 828 * 829 * The [<gio/gnetworking.h>][gio-gnetworking.h] 830 * header pulls in system headers that will define most of the 831 * standard/portable socket options. For unusual socket protocols or 832 * platform-dependent options, you may need to include additional 833 * headers. 834 * 835 * Note that even for socket options that are a single byte in size, 836 * @value is still a pointer to a #gint variable, not a #guchar; 837 * g_socket_get_option() will handle the conversion internally. 838 * 839 * Params: 840 * level = the "API level" of the option (eg, `SOL_SOCKET`) 841 * optname = the "name" of the option (eg, `SO_BROADCAST`) 842 * value = return location for the option value 843 * 844 * Returns: success or failure. On failure, @error will be set, and 845 * the system error value (`errno` or WSAGetLastError()) will still 846 * be set to the result of the getsockopt() call. 847 * 848 * Since: 2.36 849 * 850 * Throws: GException on failure. 851 */ 852 public bool getOption(int level, int optname, out int value) 853 { 854 GError* err = null; 855 856 auto p = g_socket_get_option(gSocket, level, optname, &value, &err) != 0; 857 858 if (err !is null) 859 { 860 throw new GException( new ErrorG(err) ); 861 } 862 863 return p; 864 } 865 866 /** 867 * Gets the socket protocol id the socket was created with. 868 * In case the protocol is unknown, -1 is returned. 869 * 870 * Returns: a protocol id, or -1 if unknown 871 * 872 * Since: 2.22 873 */ 874 public GSocketProtocol getProtocol() 875 { 876 return g_socket_get_protocol(gSocket); 877 } 878 879 /** 880 * Try to get the remove address of a connected socket. This is only 881 * useful for connection oriented sockets that have been connected. 882 * 883 * Returns: a #GSocketAddress or %NULL on error. 884 * Free the returned object with g_object_unref(). 885 * 886 * Since: 2.22 887 * 888 * Throws: GException on failure. 889 */ 890 public SocketAddress getRemoteAddress() 891 { 892 GError* err = null; 893 894 auto p = g_socket_get_remote_address(gSocket, &err); 895 896 if (err !is null) 897 { 898 throw new GException( new ErrorG(err) ); 899 } 900 901 if(p is null) 902 { 903 return null; 904 } 905 906 return ObjectG.getDObject!(SocketAddress)(cast(GSocketAddress*) p, true); 907 } 908 909 /** 910 * Gets the socket type of the socket. 911 * 912 * Returns: a #GSocketType 913 * 914 * Since: 2.22 915 */ 916 public GSocketType getSocketType() 917 { 918 return g_socket_get_socket_type(gSocket); 919 } 920 921 /** 922 * Gets the timeout setting of the socket. For details on this, see 923 * g_socket_set_timeout(). 924 * 925 * Returns: the timeout in seconds 926 * 927 * Since: 2.26 928 */ 929 public uint getTimeout() 930 { 931 return g_socket_get_timeout(gSocket); 932 } 933 934 /** 935 * Gets the unicast time-to-live setting on @socket; see 936 * g_socket_set_ttl() for more details. 937 * 938 * Returns: the time-to-live setting on @socket 939 * 940 * Since: 2.32 941 */ 942 public uint getTtl() 943 { 944 return g_socket_get_ttl(gSocket); 945 } 946 947 /** 948 * Checks whether a socket is closed. 949 * 950 * Returns: %TRUE if socket is closed, %FALSE otherwise 951 * 952 * Since: 2.22 953 */ 954 public bool isClosed() 955 { 956 return g_socket_is_closed(gSocket) != 0; 957 } 958 959 /** 960 * Check whether the socket is connected. This is only useful for 961 * connection-oriented sockets. 962 * 963 * If using g_socket_shutdown(), this function will return %TRUE until the 964 * socket has been shut down for reading and writing. If you do a non-blocking 965 * connect, this function will not return %TRUE until after you call 966 * g_socket_check_connect_result(). 967 * 968 * Returns: %TRUE if socket is connected, %FALSE otherwise. 969 * 970 * Since: 2.22 971 */ 972 public bool isConnected() 973 { 974 return g_socket_is_connected(gSocket) != 0; 975 } 976 977 /** 978 * Registers @socket to receive multicast messages sent to @group. 979 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have 980 * been bound to an appropriate interface and port with 981 * g_socket_bind(). 982 * 983 * If @iface is %NULL, the system will automatically pick an interface 984 * to bind to based on @group. 985 * 986 * If @source_specific is %TRUE, source-specific multicast as defined 987 * in RFC 4604 is used. Note that on older platforms this may fail 988 * with a %G_IO_ERROR_NOT_SUPPORTED error. 989 * 990 * Params: 991 * group = a #GInetAddress specifying the group address to join. 992 * sourceSpecific = %TRUE if source-specific multicast should be used 993 * iface = Name of the interface to use, or %NULL 994 * 995 * Returns: %TRUE on success, %FALSE on error. 996 * 997 * Since: 2.32 998 * 999 * Throws: GException on failure. 1000 */ 1001 public bool joinMulticastGroup(InetAddress group, bool sourceSpecific, string iface) 1002 { 1003 GError* err = null; 1004 1005 auto p = g_socket_join_multicast_group(gSocket, (group is null) ? null : group.getInetAddressStruct(), sourceSpecific, Str.toStringz(iface), &err) != 0; 1006 1007 if (err !is null) 1008 { 1009 throw new GException( new ErrorG(err) ); 1010 } 1011 1012 return p; 1013 } 1014 1015 /** 1016 * Removes @socket from the multicast group defined by @group, @iface, 1017 * and @source_specific (which must all have the same values they had 1018 * when you joined the group). 1019 * 1020 * @socket remains bound to its address and port, and can still receive 1021 * unicast messages after calling this. 1022 * 1023 * Params: 1024 * group = a #GInetAddress specifying the group address to leave. 1025 * sourceSpecific = %TRUE if source-specific multicast was used 1026 * iface = Interface used 1027 * 1028 * Returns: %TRUE on success, %FALSE on error. 1029 * 1030 * Since: 2.32 1031 * 1032 * Throws: GException on failure. 1033 */ 1034 public bool leaveMulticastGroup(InetAddress group, bool sourceSpecific, string iface) 1035 { 1036 GError* err = null; 1037 1038 auto p = g_socket_leave_multicast_group(gSocket, (group is null) ? null : group.getInetAddressStruct(), sourceSpecific, Str.toStringz(iface), &err) != 0; 1039 1040 if (err !is null) 1041 { 1042 throw new GException( new ErrorG(err) ); 1043 } 1044 1045 return p; 1046 } 1047 1048 /** 1049 * Marks the socket as a server socket, i.e. a socket that is used 1050 * to accept incoming requests using g_socket_accept(). 1051 * 1052 * Before calling this the socket must be bound to a local address using 1053 * g_socket_bind(). 1054 * 1055 * To set the maximum amount of outstanding clients, use 1056 * g_socket_set_listen_backlog(). 1057 * 1058 * Returns: %TRUE on success, %FALSE on error. 1059 * 1060 * Since: 2.22 1061 * 1062 * Throws: GException on failure. 1063 */ 1064 public bool listen() 1065 { 1066 GError* err = null; 1067 1068 auto p = g_socket_listen(gSocket, &err) != 0; 1069 1070 if (err !is null) 1071 { 1072 throw new GException( new ErrorG(err) ); 1073 } 1074 1075 return p; 1076 } 1077 1078 /** 1079 * Receive data (up to @size bytes) from a socket. This is mainly used by 1080 * connection-oriented sockets; it is identical to g_socket_receive_from() 1081 * with @address set to %NULL. 1082 * 1083 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets, 1084 * g_socket_receive() will always read either 0 or 1 complete messages from 1085 * the socket. If the received message is too large to fit in @buffer, then 1086 * the data beyond @size bytes will be discarded, without any explicit 1087 * indication that this has occurred. 1088 * 1089 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any 1090 * number of bytes, up to @size. If more than @size bytes have been 1091 * received, the additional data will be returned in future calls to 1092 * g_socket_receive(). 1093 * 1094 * If the socket is in blocking mode the call will block until there 1095 * is some data to receive, the connection is closed, or there is an 1096 * error. If there is no data available and the socket is in 1097 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be 1098 * returned. To be notified when data is available, wait for the 1099 * %G_IO_IN condition. 1100 * 1101 * On error -1 is returned and @error is set accordingly. 1102 * 1103 * Params: 1104 * buffer = a buffer to 1105 * read data into (which should be at least @size bytes long). 1106 * size = the number of bytes you want to read from the socket 1107 * cancellable = a %GCancellable or %NULL 1108 * 1109 * Returns: Number of bytes read, or 0 if the connection was closed by 1110 * the peer, or -1 on error 1111 * 1112 * Since: 2.22 1113 * 1114 * Throws: GException on failure. 1115 */ 1116 public ptrdiff_t receive(ref char[] buffer, Cancellable cancellable) 1117 { 1118 GError* err = null; 1119 1120 auto p = g_socket_receive(gSocket, buffer.ptr, cast(size_t)buffer.length, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1121 1122 if (err !is null) 1123 { 1124 throw new GException( new ErrorG(err) ); 1125 } 1126 1127 return p; 1128 } 1129 1130 /** 1131 * Receive data (up to @size bytes) from a socket. 1132 * 1133 * If @address is non-%NULL then @address will be set equal to the 1134 * source address of the received packet. 1135 * @address is owned by the caller. 1136 * 1137 * See g_socket_receive() for additional information. 1138 * 1139 * Params: 1140 * address = a pointer to a #GSocketAddress 1141 * pointer, or %NULL 1142 * buffer = a buffer to 1143 * read data into (which should be at least @size bytes long). 1144 * size = the number of bytes you want to read from the socket 1145 * cancellable = a %GCancellable or %NULL 1146 * 1147 * Returns: Number of bytes read, or 0 if the connection was closed by 1148 * the peer, or -1 on error 1149 * 1150 * Since: 2.22 1151 * 1152 * Throws: GException on failure. 1153 */ 1154 public ptrdiff_t receiveFrom(out SocketAddress address, ref char[] buffer, Cancellable cancellable) 1155 { 1156 GSocketAddress* outaddress = null; 1157 GError* err = null; 1158 1159 auto p = g_socket_receive_from(gSocket, &outaddress, buffer.ptr, cast(size_t)buffer.length, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1160 1161 if (err !is null) 1162 { 1163 throw new GException( new ErrorG(err) ); 1164 } 1165 1166 address = ObjectG.getDObject!(SocketAddress)(outaddress); 1167 1168 return p; 1169 } 1170 1171 /** 1172 * Receive data from a socket. For receiving multiple messages, see 1173 * g_socket_receive_messages(); for easier use, see 1174 * g_socket_receive() and g_socket_receive_from(). 1175 * 1176 * If @address is non-%NULL then @address will be set equal to the 1177 * source address of the received packet. 1178 * @address is owned by the caller. 1179 * 1180 * @vector must point to an array of #GInputVector structs and 1181 * @num_vectors must be the length of this array. These structs 1182 * describe the buffers that received data will be scattered into. 1183 * If @num_vectors is -1, then @vectors is assumed to be terminated 1184 * by a #GInputVector with a %NULL buffer pointer. 1185 * 1186 * As a special case, if @num_vectors is 0 (in which case, @vectors 1187 * may of course be %NULL), then a single byte is received and 1188 * discarded. This is to facilitate the common practice of sending a 1189 * single '\0' byte for the purposes of transferring ancillary data. 1190 * 1191 * @messages, if non-%NULL, will be set to point to a newly-allocated 1192 * array of #GSocketControlMessage instances or %NULL if no such 1193 * messages was received. These correspond to the control messages 1194 * received from the kernel, one #GSocketControlMessage per message 1195 * from the kernel. This array is %NULL-terminated and must be freed 1196 * by the caller using g_free() after calling g_object_unref() on each 1197 * element. If @messages is %NULL, any control messages received will 1198 * be discarded. 1199 * 1200 * @num_messages, if non-%NULL, will be set to the number of control 1201 * messages received. 1202 * 1203 * If both @messages and @num_messages are non-%NULL, then 1204 * @num_messages gives the number of #GSocketControlMessage instances 1205 * in @messages (ie: not including the %NULL terminator). 1206 * 1207 * @flags is an in/out parameter. The commonly available arguments 1208 * for this are available in the #GSocketMsgFlags enum, but the 1209 * values there are the same as the system values, and the flags 1210 * are passed in as-is, so you can pass in system-specific flags too 1211 * (and g_socket_receive_message() may pass system-specific flags out). 1212 * Flags passed in to the parameter affect the receive operation; flags returned 1213 * out of it are relevant to the specific returned message. 1214 * 1215 * As with g_socket_receive(), data may be discarded if @socket is 1216 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not 1217 * provide enough buffer space to read a complete message. You can pass 1218 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without 1219 * removing it from the receive queue, but there is no portable way to find 1220 * out the length of the message other than by reading it into a 1221 * sufficiently-large buffer. 1222 * 1223 * If the socket is in blocking mode the call will block until there 1224 * is some data to receive, the connection is closed, or there is an 1225 * error. If there is no data available and the socket is in 1226 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be 1227 * returned. To be notified when data is available, wait for the 1228 * %G_IO_IN condition. 1229 * 1230 * On error -1 is returned and @error is set accordingly. 1231 * 1232 * Params: 1233 * address = a pointer to a #GSocketAddress 1234 * pointer, or %NULL 1235 * vectors = an array of #GInputVector structs 1236 * numVectors = the number of elements in @vectors, or -1 1237 * messages = a pointer which 1238 * may be filled with an array of #GSocketControlMessages, or %NULL 1239 * numMessages = a pointer which will be filled with the number of 1240 * elements in @messages, or %NULL 1241 * flags = a pointer to an int containing #GSocketMsgFlags flags 1242 * cancellable = a %GCancellable or %NULL 1243 * 1244 * Returns: Number of bytes read, or 0 if the connection was closed by 1245 * the peer, or -1 on error 1246 * 1247 * Since: 2.22 1248 * 1249 * Throws: GException on failure. 1250 */ 1251 public ptrdiff_t receiveMessage(out SocketAddress address, GInputVector[] vectors, out SocketControlMessage[] messages, ref int flags, Cancellable cancellable) 1252 { 1253 GSocketAddress* outaddress = null; 1254 GSocketControlMessage** outmessages = null; 1255 int numMessages; 1256 GError* err = null; 1257 1258 auto p = g_socket_receive_message(gSocket, &outaddress, vectors.ptr, cast(int)vectors.length, &outmessages, &numMessages, &flags, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1259 1260 if (err !is null) 1261 { 1262 throw new GException( new ErrorG(err) ); 1263 } 1264 1265 address = ObjectG.getDObject!(SocketAddress)(outaddress); 1266 1267 messages = new SocketControlMessage[numMessages]; 1268 for(size_t i = 0; i < numMessages; i++) 1269 { 1270 messages[i] = ObjectG.getDObject!(SocketControlMessage)(cast(GSocketControlMessage*) outmessages[i]); 1271 } 1272 1273 return p; 1274 } 1275 1276 /** 1277 * Receive multiple data messages from @socket in one go. This is the most 1278 * complicated and fully-featured version of this call. For easier use, see 1279 * g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message(). 1280 * 1281 * @messages must point to an array of #GInputMessage structs and 1282 * @num_messages must be the length of this array. Each #GInputMessage 1283 * contains a pointer to an array of #GInputVector structs describing the 1284 * buffers that the data received in each message will be written to. Using 1285 * multiple #GInputVectors is more memory-efficient than manually copying data 1286 * out of a single buffer to multiple sources, and more system-call-efficient 1287 * than making multiple calls to g_socket_receive(), such as in scenarios where 1288 * a lot of data packets need to be received (e.g. high-bandwidth video 1289 * streaming over RTP/UDP). 1290 * 1291 * @flags modify how all messages are received. The commonly available 1292 * arguments for this are available in the #GSocketMsgFlags enum, but the 1293 * values there are the same as the system values, and the flags 1294 * are passed in as-is, so you can pass in system-specific flags too. These 1295 * flags affect the overall receive operation. Flags affecting individual 1296 * messages are returned in #GInputMessage.flags. 1297 * 1298 * The other members of #GInputMessage are treated as described in its 1299 * documentation. 1300 * 1301 * If #GSocket:blocking is %TRUE the call will block until @num_messages have 1302 * been received, or the end of the stream is reached. 1303 * 1304 * If #GSocket:blocking is %FALSE the call will return up to @num_messages 1305 * without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the 1306 * operating system to be received. 1307 * 1308 * In blocking mode, if #GSocket:timeout is positive and is reached before any 1309 * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to 1310 * @num_messages are returned. (Note: This is effectively the 1311 * behaviour of `MSG_WAITFORONE` with recvmmsg().) 1312 * 1313 * To be notified when messages are available, wait for the 1314 * %G_IO_IN condition. Note though that you may still receive 1315 * %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were 1316 * previously notified of a %G_IO_IN condition. 1317 * 1318 * If the remote peer closes the connection, any messages queued in the 1319 * operating system will be returned, and subsequent calls to 1320 * g_socket_receive_messages() will return 0 (with no error set). 1321 * 1322 * On error -1 is returned and @error is set accordingly. An error will only 1323 * be returned if zero messages could be received; otherwise the number of 1324 * messages successfully received before the error will be returned. 1325 * 1326 * Params: 1327 * messages = an array of #GInputMessage structs 1328 * numMessages = the number of elements in @messages 1329 * flags = an int containing #GSocketMsgFlags flags for the overall operation 1330 * cancellable = a %GCancellable or %NULL 1331 * 1332 * Returns: number of messages received, or -1 on error. Note that the number 1333 * of messages received may be smaller than @num_messages if in non-blocking 1334 * mode, if the peer closed the connection, or if @num_messages 1335 * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try 1336 * to receive the remaining messages. 1337 * 1338 * Since: 2.48 1339 * 1340 * Throws: GException on failure. 1341 */ 1342 public int receiveMessages(GInputMessage[] messages, int flags, Cancellable cancellable) 1343 { 1344 GError* err = null; 1345 1346 auto p = g_socket_receive_messages(gSocket, messages.ptr, cast(uint)messages.length, flags, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1347 1348 if (err !is null) 1349 { 1350 throw new GException( new ErrorG(err) ); 1351 } 1352 1353 return p; 1354 } 1355 1356 /** 1357 * This behaves exactly the same as g_socket_receive(), except that 1358 * the choice of blocking or non-blocking behavior is determined by 1359 * the @blocking argument rather than by @socket's properties. 1360 * 1361 * Params: 1362 * buffer = a buffer to 1363 * read data into (which should be at least @size bytes long). 1364 * size = the number of bytes you want to read from the socket 1365 * blocking = whether to do blocking or non-blocking I/O 1366 * cancellable = a %GCancellable or %NULL 1367 * 1368 * Returns: Number of bytes read, or 0 if the connection was closed by 1369 * the peer, or -1 on error 1370 * 1371 * Since: 2.26 1372 * 1373 * Throws: GException on failure. 1374 */ 1375 public ptrdiff_t receiveWithBlocking(string buffer, bool blocking, Cancellable cancellable) 1376 { 1377 GError* err = null; 1378 1379 auto p = g_socket_receive_with_blocking(gSocket, Str.toStringz(buffer), cast(size_t)buffer.length, blocking, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1380 1381 if (err !is null) 1382 { 1383 throw new GException( new ErrorG(err) ); 1384 } 1385 1386 return p; 1387 } 1388 1389 /** 1390 * Tries to send @size bytes from @buffer on the socket. This is 1391 * mainly used by connection-oriented sockets; it is identical to 1392 * g_socket_send_to() with @address set to %NULL. 1393 * 1394 * If the socket is in blocking mode the call will block until there is 1395 * space for the data in the socket queue. If there is no space available 1396 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error 1397 * will be returned. To be notified when space is available, wait for the 1398 * %G_IO_OUT condition. Note though that you may still receive 1399 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously 1400 * notified of a %G_IO_OUT condition. (On Windows in particular, this is 1401 * very common due to the way the underlying APIs work.) 1402 * 1403 * On error -1 is returned and @error is set accordingly. 1404 * 1405 * Params: 1406 * buffer = the buffer 1407 * containing the data to send. 1408 * size = the number of bytes to send 1409 * cancellable = a %GCancellable or %NULL 1410 * 1411 * Returns: Number of bytes written (which may be less than @size), or -1 1412 * on error 1413 * 1414 * Since: 2.22 1415 * 1416 * Throws: GException on failure. 1417 */ 1418 public ptrdiff_t send(string buffer, Cancellable cancellable) 1419 { 1420 GError* err = null; 1421 1422 auto p = g_socket_send(gSocket, Str.toStringz(buffer), cast(size_t)buffer.length, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1423 1424 if (err !is null) 1425 { 1426 throw new GException( new ErrorG(err) ); 1427 } 1428 1429 return p; 1430 } 1431 1432 /** 1433 * Send data to @address on @socket. For sending multiple messages see 1434 * g_socket_send_messages(); for easier use, see 1435 * g_socket_send() and g_socket_send_to(). 1436 * 1437 * If @address is %NULL then the message is sent to the default receiver 1438 * (set by g_socket_connect()). 1439 * 1440 * @vectors must point to an array of #GOutputVector structs and 1441 * @num_vectors must be the length of this array. (If @num_vectors is -1, 1442 * then @vectors is assumed to be terminated by a #GOutputVector with a 1443 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers 1444 * that the sent data will be gathered from. Using multiple 1445 * #GOutputVectors is more memory-efficient than manually copying 1446 * data from multiple sources into a single buffer, and more 1447 * network-efficient than making multiple calls to g_socket_send(). 1448 * 1449 * @messages, if non-%NULL, is taken to point to an array of @num_messages 1450 * #GSocketControlMessage instances. These correspond to the control 1451 * messages to be sent on the socket. 1452 * If @num_messages is -1 then @messages is treated as a %NULL-terminated 1453 * array. 1454 * 1455 * @flags modify how the message is sent. The commonly available arguments 1456 * for this are available in the #GSocketMsgFlags enum, but the 1457 * values there are the same as the system values, and the flags 1458 * are passed in as-is, so you can pass in system-specific flags too. 1459 * 1460 * If the socket is in blocking mode the call will block until there is 1461 * space for the data in the socket queue. If there is no space available 1462 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error 1463 * will be returned. To be notified when space is available, wait for the 1464 * %G_IO_OUT condition. Note though that you may still receive 1465 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously 1466 * notified of a %G_IO_OUT condition. (On Windows in particular, this is 1467 * very common due to the way the underlying APIs work.) 1468 * 1469 * On error -1 is returned and @error is set accordingly. 1470 * 1471 * Params: 1472 * address = a #GSocketAddress, or %NULL 1473 * vectors = an array of #GOutputVector structs 1474 * numVectors = the number of elements in @vectors, or -1 1475 * messages = a pointer to an 1476 * array of #GSocketControlMessages, or %NULL. 1477 * numMessages = number of elements in @messages, or -1. 1478 * flags = an int containing #GSocketMsgFlags flags 1479 * cancellable = a %GCancellable or %NULL 1480 * 1481 * Returns: Number of bytes written (which may be less than @size), or -1 1482 * on error 1483 * 1484 * Since: 2.22 1485 * 1486 * Throws: GException on failure. 1487 */ 1488 public ptrdiff_t sendMessage(SocketAddress address, GOutputVector[] vectors, SocketControlMessage[] messages, int flags, Cancellable cancellable) 1489 { 1490 GSocketControlMessage*[] messagesArray = new GSocketControlMessage*[messages.length]; 1491 for ( int i = 0; i < messages.length; i++ ) 1492 { 1493 messagesArray[i] = messages[i].getSocketControlMessageStruct(); 1494 } 1495 1496 GError* err = null; 1497 1498 auto p = g_socket_send_message(gSocket, (address is null) ? null : address.getSocketAddressStruct(), vectors.ptr, cast(int)vectors.length, messagesArray.ptr, cast(int)messages.length, flags, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1499 1500 if (err !is null) 1501 { 1502 throw new GException( new ErrorG(err) ); 1503 } 1504 1505 return p; 1506 } 1507 1508 /** 1509 * Send multiple data messages from @socket in one go. This is the most 1510 * complicated and fully-featured version of this call. For easier use, see 1511 * g_socket_send(), g_socket_send_to(), and g_socket_send_message(). 1512 * 1513 * @messages must point to an array of #GOutputMessage structs and 1514 * @num_messages must be the length of this array. Each #GOutputMessage 1515 * contains an address to send the data to, and a pointer to an array of 1516 * #GOutputVector structs to describe the buffers that the data to be sent 1517 * for each message will be gathered from. Using multiple #GOutputVectors is 1518 * more memory-efficient than manually copying data from multiple sources 1519 * into a single buffer, and more network-efficient than making multiple 1520 * calls to g_socket_send(). Sending multiple messages in one go avoids the 1521 * overhead of making a lot of syscalls in scenarios where a lot of data 1522 * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), 1523 * or where the same data needs to be sent to multiple recipients. 1524 * 1525 * @flags modify how the message is sent. The commonly available arguments 1526 * for this are available in the #GSocketMsgFlags enum, but the 1527 * values there are the same as the system values, and the flags 1528 * are passed in as-is, so you can pass in system-specific flags too. 1529 * 1530 * If the socket is in blocking mode the call will block until there is 1531 * space for all the data in the socket queue. If there is no space available 1532 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error 1533 * will be returned if no data was written at all, otherwise the number of 1534 * messages sent will be returned. To be notified when space is available, 1535 * wait for the %G_IO_OUT condition. Note though that you may still receive 1536 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously 1537 * notified of a %G_IO_OUT condition. (On Windows in particular, this is 1538 * very common due to the way the underlying APIs work.) 1539 * 1540 * On error -1 is returned and @error is set accordingly. An error will only 1541 * be returned if zero messages could be sent; otherwise the number of messages 1542 * successfully sent before the error will be returned. 1543 * 1544 * Params: 1545 * messages = an array of #GOutputMessage structs 1546 * numMessages = the number of elements in @messages 1547 * flags = an int containing #GSocketMsgFlags flags 1548 * cancellable = a %GCancellable or %NULL 1549 * 1550 * Returns: number of messages sent, or -1 on error. Note that the number of 1551 * messages sent may be smaller than @num_messages if the socket is 1552 * non-blocking or if @num_messages was larger than UIO_MAXIOV (1024), 1553 * in which case the caller may re-try to send the remaining messages. 1554 * 1555 * Since: 2.44 1556 * 1557 * Throws: GException on failure. 1558 */ 1559 public int sendMessages(GOutputMessage[] messages, int flags, Cancellable cancellable) 1560 { 1561 GError* err = null; 1562 1563 auto p = g_socket_send_messages(gSocket, messages.ptr, cast(uint)messages.length, flags, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1564 1565 if (err !is null) 1566 { 1567 throw new GException( new ErrorG(err) ); 1568 } 1569 1570 return p; 1571 } 1572 1573 /** 1574 * Tries to send @size bytes from @buffer to @address. If @address is 1575 * %NULL then the message is sent to the default receiver (set by 1576 * g_socket_connect()). 1577 * 1578 * See g_socket_send() for additional information. 1579 * 1580 * Params: 1581 * address = a #GSocketAddress, or %NULL 1582 * buffer = the buffer 1583 * containing the data to send. 1584 * size = the number of bytes to send 1585 * cancellable = a %GCancellable or %NULL 1586 * 1587 * Returns: Number of bytes written (which may be less than @size), or -1 1588 * on error 1589 * 1590 * Since: 2.22 1591 * 1592 * Throws: GException on failure. 1593 */ 1594 public ptrdiff_t sendTo(SocketAddress address, string buffer, Cancellable cancellable) 1595 { 1596 GError* err = null; 1597 1598 auto p = g_socket_send_to(gSocket, (address is null) ? null : address.getSocketAddressStruct(), Str.toStringz(buffer), cast(size_t)buffer.length, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1599 1600 if (err !is null) 1601 { 1602 throw new GException( new ErrorG(err) ); 1603 } 1604 1605 return p; 1606 } 1607 1608 /** 1609 * This behaves exactly the same as g_socket_send(), except that 1610 * the choice of blocking or non-blocking behavior is determined by 1611 * the @blocking argument rather than by @socket's properties. 1612 * 1613 * Params: 1614 * buffer = the buffer 1615 * containing the data to send. 1616 * size = the number of bytes to send 1617 * blocking = whether to do blocking or non-blocking I/O 1618 * cancellable = a %GCancellable or %NULL 1619 * 1620 * Returns: Number of bytes written (which may be less than @size), or -1 1621 * on error 1622 * 1623 * Since: 2.26 1624 * 1625 * Throws: GException on failure. 1626 */ 1627 public ptrdiff_t sendWithBlocking(string buffer, bool blocking, Cancellable cancellable) 1628 { 1629 GError* err = null; 1630 1631 auto p = g_socket_send_with_blocking(gSocket, Str.toStringz(buffer), cast(size_t)buffer.length, blocking, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err); 1632 1633 if (err !is null) 1634 { 1635 throw new GException( new ErrorG(err) ); 1636 } 1637 1638 return p; 1639 } 1640 1641 /** 1642 * Sets the blocking mode of the socket. In blocking mode 1643 * all operations (which don’t take an explicit blocking parameter) block until 1644 * they succeed or there is an error. In 1645 * non-blocking mode all functions return results immediately or 1646 * with a %G_IO_ERROR_WOULD_BLOCK error. 1647 * 1648 * All sockets are created in blocking mode. However, note that the 1649 * platform level socket is always non-blocking, and blocking mode 1650 * is a GSocket level feature. 1651 * 1652 * Params: 1653 * blocking = Whether to use blocking I/O or not. 1654 * 1655 * Since: 2.22 1656 */ 1657 public void setBlocking(bool blocking) 1658 { 1659 g_socket_set_blocking(gSocket, blocking); 1660 } 1661 1662 /** 1663 * Sets whether @socket should allow sending to broadcast addresses. 1664 * This is %FALSE by default. 1665 * 1666 * Params: 1667 * broadcast = whether @socket should allow sending to broadcast 1668 * addresses 1669 * 1670 * Since: 2.32 1671 */ 1672 public void setBroadcast(bool broadcast) 1673 { 1674 g_socket_set_broadcast(gSocket, broadcast); 1675 } 1676 1677 /** 1678 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When 1679 * this flag is set on a socket, the system will attempt to verify that the 1680 * remote socket endpoint is still present if a sufficiently long period of 1681 * time passes with no data being exchanged. If the system is unable to 1682 * verify the presence of the remote endpoint, it will automatically close 1683 * the connection. 1684 * 1685 * This option is only functional on certain kinds of sockets. (Notably, 1686 * %G_SOCKET_PROTOCOL_TCP sockets.) 1687 * 1688 * The exact time between pings is system- and protocol-dependent, but will 1689 * normally be at least two hours. Most commonly, you would set this flag 1690 * on a server socket if you want to allow clients to remain idle for long 1691 * periods of time, but also want to ensure that connections are eventually 1692 * garbage-collected if clients crash or become unreachable. 1693 * 1694 * Params: 1695 * keepalive = Value for the keepalive flag 1696 * 1697 * Since: 2.22 1698 */ 1699 public void setKeepalive(bool keepalive) 1700 { 1701 g_socket_set_keepalive(gSocket, keepalive); 1702 } 1703 1704 /** 1705 * Sets the maximum number of outstanding connections allowed 1706 * when listening on this socket. If more clients than this are 1707 * connecting to the socket and the application is not handling them 1708 * on time then the new connections will be refused. 1709 * 1710 * Note that this must be called before g_socket_listen() and has no 1711 * effect if called after that. 1712 * 1713 * Params: 1714 * backlog = the maximum number of pending connections. 1715 * 1716 * Since: 2.22 1717 */ 1718 public void setListenBacklog(int backlog) 1719 { 1720 g_socket_set_listen_backlog(gSocket, backlog); 1721 } 1722 1723 /** 1724 * Sets whether outgoing multicast packets will be received by sockets 1725 * listening on that multicast address on the same host. This is %TRUE 1726 * by default. 1727 * 1728 * Params: 1729 * loopback = whether @socket should receive messages sent to its 1730 * multicast groups from the local host 1731 * 1732 * Since: 2.32 1733 */ 1734 public void setMulticastLoopback(bool loopback) 1735 { 1736 g_socket_set_multicast_loopback(gSocket, loopback); 1737 } 1738 1739 /** 1740 * Sets the time-to-live for outgoing multicast datagrams on @socket. 1741 * By default, this is 1, meaning that multicast packets will not leave 1742 * the local network. 1743 * 1744 * Params: 1745 * ttl = the time-to-live value for all multicast datagrams on @socket 1746 * 1747 * Since: 2.32 1748 */ 1749 public void setMulticastTtl(uint ttl) 1750 { 1751 g_socket_set_multicast_ttl(gSocket, ttl); 1752 } 1753 1754 /** 1755 * Sets the value of an integer-valued option on @socket, as with 1756 * setsockopt(). (If you need to set a non-integer-valued option, 1757 * you will need to call setsockopt() directly.) 1758 * 1759 * The [<gio/gnetworking.h>][gio-gnetworking.h] 1760 * header pulls in system headers that will define most of the 1761 * standard/portable socket options. For unusual socket protocols or 1762 * platform-dependent options, you may need to include additional 1763 * headers. 1764 * 1765 * Params: 1766 * level = the "API level" of the option (eg, `SOL_SOCKET`) 1767 * optname = the "name" of the option (eg, `SO_BROADCAST`) 1768 * value = the value to set the option to 1769 * 1770 * Returns: success or failure. On failure, @error will be set, and 1771 * the system error value (`errno` or WSAGetLastError()) will still 1772 * be set to the result of the setsockopt() call. 1773 * 1774 * Since: 2.36 1775 * 1776 * Throws: GException on failure. 1777 */ 1778 public bool setOption(int level, int optname, int value) 1779 { 1780 GError* err = null; 1781 1782 auto p = g_socket_set_option(gSocket, level, optname, value, &err) != 0; 1783 1784 if (err !is null) 1785 { 1786 throw new GException( new ErrorG(err) ); 1787 } 1788 1789 return p; 1790 } 1791 1792 /** 1793 * Sets the time in seconds after which I/O operations on @socket will 1794 * time out if they have not yet completed. 1795 * 1796 * On a blocking socket, this means that any blocking #GSocket 1797 * operation will time out after @timeout seconds of inactivity, 1798 * returning %G_IO_ERROR_TIMED_OUT. 1799 * 1800 * On a non-blocking socket, calls to g_socket_condition_wait() will 1801 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources 1802 * created with g_socket_create_source() will trigger after 1803 * @timeout seconds of inactivity, with the requested condition 1804 * set, at which point calling g_socket_receive(), g_socket_send(), 1805 * g_socket_check_connect_result(), etc, will fail with 1806 * %G_IO_ERROR_TIMED_OUT. 1807 * 1808 * If @timeout is 0 (the default), operations will never time out 1809 * on their own. 1810 * 1811 * Note that if an I/O operation is interrupted by a signal, this may 1812 * cause the timeout to be reset. 1813 * 1814 * Params: 1815 * timeout = the timeout for @socket, in seconds, or 0 for none 1816 * 1817 * Since: 2.26 1818 */ 1819 public void setTimeout(uint timeout) 1820 { 1821 g_socket_set_timeout(gSocket, timeout); 1822 } 1823 1824 /** 1825 * Sets the time-to-live for outgoing unicast packets on @socket. 1826 * By default the platform-specific default value is used. 1827 * 1828 * Params: 1829 * ttl = the time-to-live value for all unicast packets on @socket 1830 * 1831 * Since: 2.32 1832 */ 1833 public void setTtl(uint ttl) 1834 { 1835 g_socket_set_ttl(gSocket, ttl); 1836 } 1837 1838 /** 1839 * Shut down part or all of a full-duplex connection. 1840 * 1841 * If @shutdown_read is %TRUE then the receiving side of the connection 1842 * is shut down, and further reading is disallowed. 1843 * 1844 * If @shutdown_write is %TRUE then the sending side of the connection 1845 * is shut down, and further writing is disallowed. 1846 * 1847 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. 1848 * 1849 * One example where it is useful to shut down only one side of a connection is 1850 * graceful disconnect for TCP connections where you close the sending side, 1851 * then wait for the other side to close the connection, thus ensuring that the 1852 * other side saw all sent data. 1853 * 1854 * Params: 1855 * shutdownRead = whether to shut down the read side 1856 * shutdownWrite = whether to shut down the write side 1857 * 1858 * Returns: %TRUE on success, %FALSE on error 1859 * 1860 * Since: 2.22 1861 * 1862 * Throws: GException on failure. 1863 */ 1864 public bool shutdown(bool shutdownRead, bool shutdownWrite) 1865 { 1866 GError* err = null; 1867 1868 auto p = g_socket_shutdown(gSocket, shutdownRead, shutdownWrite, &err) != 0; 1869 1870 if (err !is null) 1871 { 1872 throw new GException( new ErrorG(err) ); 1873 } 1874 1875 return p; 1876 } 1877 1878 /** 1879 * Checks if a socket is capable of speaking IPv4. 1880 * 1881 * IPv4 sockets are capable of speaking IPv4. On some operating systems 1882 * and under some combinations of circumstances IPv6 sockets are also 1883 * capable of speaking IPv4. See RFC 3493 section 3.7 for more 1884 * information. 1885 * 1886 * No other types of sockets are currently considered as being capable 1887 * of speaking IPv4. 1888 * 1889 * Returns: %TRUE if this socket can be used with IPv4. 1890 * 1891 * Since: 2.22 1892 */ 1893 public bool speaksIpv4() 1894 { 1895 return g_socket_speaks_ipv4(gSocket) != 0; 1896 } 1897 }