interface/socket.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        socket.h
   3 // Purpose:     interface of wxIPV4address
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxIPV4address
  11     @wxheader{socket.h}
  12
  13
  14     @library{wxbase}
  15     @category{net}
  16 */
  17 class wxIPV4address : public wxIPaddress
  18 {
  19 public:
  20     /**
  21         Set address to any of the addresses of the current machine. Whenever
  22         possible, use this function instead of LocalHost(),
  23         as this correctly handles multi-homed hosts and avoids other small
  24         problems. Internally, this is the same as setting the IP address
  25         to @b INADDR_ANY.
  26
  27         @return Returns @true on success, @false if something went wrong.
  28     */
  29     bool AnyAddress();
  30
  31     //@{
  32     /**
  33         Returns the hostname which matches the IP address.
  34     */
  35     bool Hostname(const wxString& hostname);
  36     Return value wxString  Hostname();
  37     //@}
  38
  39     /**
  40         Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
  41     */
  42     wxString IPAddress();
  43
  44     /**
  45         Set address to localhost (127.0.0.1). Whenever possible, use the
  46         AnyAddress(),
  47         function instead of this one, as this will correctly handle multi-homed
  48         hosts and avoid other small problems.
  49     */
  50     bool LocalHost();
  51
  52     //@{
  53     /**
  54         Returns the current service.
  55     */
  56     bool Service(const wxString& service);
  57     Return value bool Service(unsigned short service);
  58     Return value unsigned short Service();
  59     //@}
  60 };
  61
  62
  63
  64 /**
  65     @class wxSocketServer
  66     @wxheader{socket.h}
  67
  68
  69     @library{wxnet}
  70     @category{net}
  71
  72     @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify,
  73     wxSocketBase::Notify, wxSocketServer::AcceptWith
  74 */
  75 class wxSocketServer : public wxSocketBase
  76 {
  77 public:
  78     /**
  79         Constructs a new server and tries to bind to the specified @e address.
  80         Before trying to accept new connections, test whether it succeeded with
  81         @ref wxSocketBase::isok wxSocketBase:IsOk.
  82
  83         @param address
  84             Specifies the local address for the server (e.g. port number).
  85         @param flags
  86             Socket flags (See wxSocketBase::SetFlags)
  87     */
  88     wxSocketServer(const wxSockAddress& address,
  89                    wxSocketFlags flags = wxSOCKET_NONE);
  90
  91     /**
  92         Destructor (it doesn't close the accepted connections).
  93     */
  94     ~wxSocketServer();
  95
  96     /**
  97         Accepts an incoming connection request, and creates a new
  98         wxSocketBase object which represents
  99         the server-side of the connection.
 100         If @a wait is @true and there are no pending connections to be
 101         accepted, it will wait for the next incoming connection to
 102         arrive. @b Warning: This will block the GUI.
 103         If @a wait is @false, it will try to accept a pending connection
 104         if there is one, but it will always return immediately without blocking
 105         the GUI. If you want to use Accept in this way, you can either check for
 106         incoming connections with WaitForAccept()
 107         or catch @b wxSOCKET_CONNECTION events, then call Accept once you know
 108         that there is an incoming connection waiting to be accepted.
 109
 110         @return Returns an opened socket connection, or @NULL if an error
 111                  occurred or if the wait parameter was @false and there
 112                  were no pending connections.
 113
 114         @see WaitForAccept(), wxSocketBase::SetNotify,
 115              wxSocketBase::Notify, AcceptWith()
 116     */
 117     wxSocketBase* Accept(bool wait = true);
 118
 119     /**
 120         Accept an incoming connection using the specified socket object.
 121
 122         @param socket
 123             Socket to be initialized
 124
 125         @return Returns @true on success, or @false if an error occurred or if the
 126                  wait parameter was @false and there were no pending
 127                  connections.
 128     */
 129     bool AcceptWith(wxSocketBase& socket, bool wait = true);
 130
 131     /**
 132         This function waits for an incoming connection. Use it if you want to call
 133         Accept() or AcceptWith()
 134         with @e wait set to @false, to detect when an incoming connection is waiting
 135         to be accepted.
 136
 137         @param seconds
 138             Number of seconds to wait.
 139             If -1, it will wait for the default timeout,
 140             as set with SetTimeout.
 141         @param millisecond
 142             Number of milliseconds to wait.
 143
 144         @return Returns @true if an incoming connection arrived, @false if the
 145                  timeout elapsed.
 146     */
 147     bool WaitForAccept(long seconds = -1, long millisecond = 0);
 148 };
 149
 150
 151
 152 /**
 153     @class wxIPaddress
 154     @wxheader{socket.h}
 155
 156     wxIPaddress is an abstract base class for all internet protocol address
 157     objects. Currently, only wxIPV4address
 158     is implemented. An experimental implementation for IPV6, wxIPV6address,
 159     is being developed.
 160
 161     @library{wxbase}
 162     @category{net}
 163 */
 164 class wxIPaddress : public wxSockAddress
 165 {
 166 public:
 167     /**
 168         Internally, this is the same as setting the IP address
 169         to @b INADDR_ANY.
 170         On IPV4 implementations, 0.0.0.0
 171         On IPV6 implementations, ::
 172
 173         @return Returns @true on success, @false if something went wrong.
 174     */
 175     virtual bool AnyAddress();
 176
 177     /**
 178         Internally, this is the same as setting the IP address
 179         to @b INADDR_BROADCAST.
 180         On IPV4 implementations, 255.255.255.255
 181
 182         @return Returns @true on success, @false if something went wrong.
 183     */
 184     virtual bool BroadcastAddress();
 185
 186     //@{
 187     /**
 188         Returns the hostname which matches the IP address.
 189     */
 190     virtual bool Hostname(const wxString& hostname);
 191     Return value virtual wxString  Hostname();
 192     //@}
 193
 194     /**
 195         Returns a wxString containing the IP address.
 196     */
 197     virtual wxString IPAddress();
 198
 199     /**
 200         Determines if current address is set to localhost.
 201     */
 202     virtual bool IsLocalHost();
 203
 204     /**
 205         Set address to localhost.
 206         On IPV4 implementations, 127.0.0.1
 207         On IPV6 implementations, ::1
 208
 209         @return Returns @true on success, @false if something went wrong.
 210     */
 211     virtual bool LocalHost();
 212
 213     //@{
 214     /**
 215         Returns the current service.
 216     */
 217     virtual bool Service(const wxString& service);
 218     Return value virtual bool Service(unsigned short service);
 219     Return value virtual unsigned short Service();
 220     //@}
 221 };
 222
 223
 224
 225 /**
 226     @class wxSocketClient
 227     @wxheader{socket.h}
 228
 229
 230     @library{wxnet}
 231     @category{net}
 232
 233     @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify,
 234     wxSocketBase::Notify
 235 */
 236 class wxSocketClient : public wxSocketBase
 237 {
 238 public:
 239     /**
 240         Constructor.
 241
 242         @param flags
 243             Socket flags (See wxSocketBase::SetFlags)
 244     */
 245     wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE);
 246
 247     /**
 248         Destructor. Please see wxSocketBase::Destroy.
 249     */
 250     ~wxSocketClient();
 251
 252     //@{
 253     /**
 254         Connects to a server using the specified address.
 255         If @a wait is @true, Connect will wait until the connection
 256         completes. @b Warning: This will block the GUI.
 257         If @a wait is @false, Connect will try to establish the connection and
 258         return immediately, without blocking the GUI. When used this way, even if
 259         Connect returns @false, the connection request can be completed later.
 260         To detect this, use WaitOnConnect(),
 261         or catch @b wxSOCKET_CONNECTION events (for successful establishment)
 262         and @b wxSOCKET_LOST events (for connection failure).
 263
 264         @param address
 265             Address of the server.
 266         @param local
 267             Bind to the specified local address and port before connecting.
 268             The local address and port can also be set using SetLocal,
 269             and then using the 2-parameter Connect method.
 270         @param wait
 271             If @true, waits for the connection to complete.
 272
 273         @return Returns @true if the connection is established and no error
 274                  occurs.
 275
 276         @see WaitOnConnect(), wxSocketBase::SetNotify,
 277              wxSocketBase::Notify
 278     */
 279     bool Connect(wxSockAddress& address, bool wait = true);
 280     bool Connect(wxSockAddress& address, wxSockAddress& local,
 281                  bool wait = true);
 282     //@}
 283
 284     /**
 285         Wait until a connection request completes, or until the specified timeout
 286         elapses. Use this function after issuing a call
 287         to Connect() with @e wait set to @false.
 288
 289         @param seconds
 290             Number of seconds to wait.
 291             If -1, it will wait for the default timeout,
 292             as set with SetTimeout.
 293         @param millisecond
 294             Number of milliseconds to wait.
 295
 296         @return WaitOnConnect returns @true if the connection request completes.
 297                  This does not necessarily mean that the connection was
 298                  successfully established; it might also happen that the
 299                  connection was refused by the peer. Use  IsConnected to
 300                  distinguish between these two situations.
 301     */
 302     bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
 303 };
 304
 305
 306
 307 /**
 308     @class wxSockAddress
 309     @wxheader{socket.h}
 310
 311     You are unlikely to need to use this class: only wxSocketBase uses it.
 312
 313     @library{wxbase}
 314     @category{FIXME}
 315
 316     @see wxSocketBase, wxIPaddress, wxIPV4address
 317 */
 318 class wxSockAddress : public wxObject
 319 {
 320 public:
 321     /**
 322         Default constructor.
 323     */
 324     wxSockAddress();
 325
 326     /**
 327         Default destructor.
 328     */
 329     ~wxSockAddress();
 330
 331     /**
 332         Delete all informations about the address.
 333     */
 334     void Clear();
 335
 336     /**
 337         Returns the length of the socket address.
 338     */
 339     int SockAddrLen();
 340 };
 341
 342
 343
 344 /**
 345     @class wxSocketEvent
 346     @wxheader{socket.h}
 347
 348     This event class contains information about socket events.
 349
 350     @library{wxnet}
 351     @category{net}
 352
 353     @see wxSocketBase, wxSocketClient, wxSocketServer
 354 */
 355 class wxSocketEvent : public wxEvent
 356 {
 357 public:
 358     /**
 359         Constructor.
 360     */
 361     wxSocketEvent(int id = 0);
 362
 363     /**
 364         Gets the client data of the socket which generated this event, as
 365         set with wxSocketBase::SetClientData.
 366     */
 367     void* GetClientData();
 368
 369     /**
 370         Returns the socket object to which this event refers to. This makes
 371         it possible to use the same event handler for different sockets.
 372     */
 373     wxSocketBase* GetSocket() const;
 374
 375     /**
 376         Returns the socket event type.
 377     */
 378     wxSocketNotify GetSocketEvent() const;
 379 };
 380
 381
 382
 383 /**
 384     @class wxSocketBase
 385     @wxheader{socket.h}
 386
 387     wxSocketBase is the base class for all socket-related objects, and it
 388     defines all basic IO functionality.
 389
 390     Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x)
 391     If you want to use sockets or derived classes such as wxFTP in a secondary
 392     thread,
 393     call wxSocketBase::Initialize() (undocumented) from the main thread before
 394     creating
 395     any sockets - in wxApp::OnInit for example.
 396     See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
 397     http://www.litwindow.com/knowhow/knowhow.html for more details.
 398
 399     @library{wxnet}
 400     @category{net}
 401
 402     @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets
 403     "Sockets sample"
 404 */
 405 class wxSocketBase : public wxObject
 406 {
 407 public:
 408     /**
 409         Default constructor. Don't use it directly; instead, use
 410         wxSocketClient to construct a socket client, or
 411         wxSocketServer to construct a socket server.
 412     */
 413     wxSocketBase();
 414
 415     /**
 416         Destructor. Do not destroy a socket using the delete operator directly;
 417         use Destroy() instead. Also, do not create
 418         socket objects in the stack.
 419     */
 420     ~wxSocketBase();
 421
 422     /**
 423         Functions that perform basic IO functionality.
 424         Close()
 425
 426         Discard()
 427
 428         Peek()
 429
 430         Read()
 431
 432         ReadMsg()
 433
 434         Unread()
 435
 436         Write()
 437
 438         WriteMsg()
 439         Functions that perform a timed wait on a certain IO condition.
 440         InterruptWait()
 441
 442         Wait()
 443
 444         WaitForLost()
 445
 446         WaitForRead()
 447
 448         WaitForWrite()
 449
 450         and also:
 451         wxSocketServer::WaitForAccept
 452
 453         wxSocketClient::WaitOnConnect
 454         Functions that allow applications to customize socket IO as needed.
 455         GetFlags()
 456
 457         SetFlags()
 458
 459         SetTimeout()
 460
 461         SetLocal()
 462     */
 463
 464
 465     /**
 466         This function shuts down the socket, disabling further transmission and
 467         reception of data; it also disables events for the socket and frees the
 468         associated system resources. Upon socket destruction, Close is automatically
 469         called, so in most cases you won't need to do it yourself, unless you
 470         explicitly want to shut down the socket, typically to notify the peer
 471         that you are closing the connection.
 472     */
 473     void Close();
 474
 475     /**
 476         @ref construct() wxSocketBase
 477
 478         @ref destruct() ~wxSocketBase
 479
 480         Destroy()
 481     */
 482
 483
 484     /**
 485         Destroys the socket safely. Use this function instead of the delete operator,
 486         since otherwise socket events could reach the application even after the
 487         socket has been destroyed. To prevent this problem, this function appends
 488         the wxSocket to a list of object to be deleted on idle time, after all
 489         events have been processed. For the same reason, you should avoid creating
 490         socket objects in the stack.
 491         Destroy calls Close() automatically.
 492
 493         @return Always @true.
 494     */
 495     bool Destroy();
 496
 497     /**
 498         This function simply deletes all bytes in the incoming queue. This function
 499         always returns immediately and its operation is not affected by IO flags.
 500         Use LastCount() to verify the number of bytes actually discarded.
 501         If you use Error(), it will always return @false.
 502     */
 503     wxSocketBase Discard();
 504
 505     /**
 506         Returns @true if an error occurred in the last IO operation.
 507         Use this function to check for an error condition after one of the
 508         following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
 509     */
 510     bool Error() const;
 511
 512     /**
 513         Returns a pointer of the client data for this socket, as set with
 514         SetClientData()
 515     */
 516     void* GetClientData() const;
 517
 518     /**
 519         Returns current IO flags, as set with SetFlags()
 520     */
 521     wxSocketFlags GetFlags() const;
 522
 523     /**
 524         This function returns the local address field of the socket. The local
 525         address field contains the complete local address of the socket (local
 526         address, local port, ...).
 527
 528         @return @true if no error happened, @false otherwise.
 529     */
 530     bool GetLocal(wxSockAddress& addr) const;
 531
 532     /**
 533         This function returns the peer address field of the socket. The peer
 534         address field contains the complete peer host address of the socket
 535         (address, port, ...).
 536
 537         @return @true if no error happened, @false otherwise.
 538     */
 539     bool GetPeer(wxSockAddress& addr) const;
 540
 541     /**
 542         Functions that allow applications to receive socket events.
 543         Notify()
 544
 545         SetNotify()
 546
 547         GetClientData()
 548
 549         SetClientData()
 550
 551         SetEventHandler()
 552     */
 553
 554
 555     /**
 556         Use this function to interrupt any wait operation currently in progress.
 557         Note that this is not intended as a regular way to interrupt a Wait call,
 558         but only as an escape mechanism for exceptional situations where it is
 559         absolutely necessary to use it, for example to abort an operation due to
 560         some exception or abnormal problem. InterruptWait is automatically called
 561         when you Close() a socket (and thus also upon
 562         socket destruction), so you don't need to use it in these cases.
 563         Wait(),
 564         wxSocketServer::WaitForAccept,
 565         WaitForLost(),
 566         WaitForRead(),
 567         WaitForWrite(),
 568         wxSocketClient::WaitOnConnect
 569     */
 570     void InterruptWait();
 571
 572     /**
 573         Returns @true if the socket is connected.
 574     */
 575     bool IsConnected() const;
 576
 577     /**
 578         This function waits until the socket is readable. This might mean that
 579         queued data is available for reading or, for streamed sockets, that
 580         the connection has been closed, so that a read operation will complete
 581         immediately without blocking (unless the @b wxSOCKET_WAITALL flag
 582         is set, in which case the operation might still block).
 583     */
 584     bool IsData() const;
 585
 586     /**
 587         Returns @true if the socket is not connected.
 588     */
 589     bool IsDisconnected() const;
 590
 591     /**
 592         Returns @true if the socket is initialized and ready and @false in other
 593         cases.
 594     */
 595     bool IsOk() const;
 596
 597     /**
 598         Returns the number of bytes read or written by the last IO call.
 599         Use this function to get the number of bytes actually transferred
 600         after using one of the following IO calls: Discard, Peek, Read,
 601         ReadMsg, Unread, Write, WriteMsg.
 602     */
 603     wxUint32 LastCount() const;
 604
 605     /**
 606         Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket
 607         errors".
 608         Please note that this function merely returns the last error code,
 609         but it should not be used to determine if an error has occurred (this
 610         is because successful operations do not change the LastError value).
 611         Use Error() first, in order to determine
 612         if the last IO call failed. If this returns @true, use LastError
 613         to discover the cause of the error.
 614     */
 615     wxSocketError LastError() const;
 616
 617     /**
 618         According to the @a notify value, this function enables
 619         or disables socket events. If @a notify is @true, the events
 620         configured with SetNotify() will
 621         be sent to the application. If @a notify is @false; no events
 622         will be sent.
 623     */
 624     void Notify(bool notify);
 625
 626     /**
 627         This function peeks a buffer of @a nbytes bytes from the socket.
 628         Peeking a buffer doesn't delete it from the socket input queue.
 629         Use LastCount() to verify the number of bytes actually peeked.
 630         Use Error() to determine if the operation succeeded.
 631
 632         @param buffer
 633             Buffer where to put peeked data.
 634         @param nbytes
 635             Number of bytes.
 636
 637         @return Returns a reference to the current object.
 638
 639         @see Error(), LastError(), LastCount(),
 640              SetFlags()
 641     */
 642     wxSocketBase Peek(void* buffer, wxUint32 nbytes);
 643
 644     /**
 645         This function reads a buffer of @a nbytes bytes from the socket.
 646         Use LastCount() to verify the number of bytes actually read.
 647         Use Error() to determine if the operation succeeded.
 648
 649         @param buffer
 650             Buffer where to put read data.
 651         @param nbytes
 652             Number of bytes.
 653
 654         @return Returns a reference to the current object.
 655
 656         @see Error(), LastError(), LastCount(),
 657              SetFlags()
 658     */
 659     wxSocketBase Read(void* buffer, wxUint32 nbytes);
 660
 661     /**
 662         This function reads a buffer sent by WriteMsg()
 663         on a socket. If the buffer passed to the function isn't big enough, the
 664         remaining bytes will be discarded. This function always waits for the
 665         buffer to be entirely filled, unless an error occurs.
 666         Use LastCount() to verify the number of bytes actually read.
 667         Use Error() to determine if the operation succeeded.
 668
 669         @param buffer
 670             Buffer where to put read data.
 671         @param nbytes
 672             Size of the buffer.
 673
 674         @return Returns a reference to the current object.
 675
 676         @see Error(), LastError(), LastCount(),
 677              SetFlags(), WriteMsg()
 678     */
 679     wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes);
 680
 681     /**
 682         This function restores the previous state of the socket, as saved
 683         with SaveState()
 684         Calls to SaveState and RestoreState can be nested.
 685
 686         @see SaveState()
 687     */
 688     void RestoreState();
 689
 690     /**
 691         This function saves the current state of the socket in a stack. Socket
 692         state includes flags, as set with SetFlags(),
 693         event mask, as set with SetNotify() and
 694         Notify(), user data, as set with
 695         SetClientData().
 696         Calls to SaveState and RestoreState can be nested.
 697
 698         @see RestoreState()
 699     */
 700     void SaveState();
 701
 702     /**
 703         Sets user-supplied client data for this socket. All socket events will
 704         contain a pointer to this data, which can be retrieved with
 705         the wxSocketEvent::GetClientData function.
 706     */
 707     void SetClientData(void* data);
 708
 709     /**
 710         Sets an event handler to be called when a socket event occurs. The
 711         handler will be called for those events for which notification is
 712         enabled with SetNotify() and
 713         Notify().
 714
 715         @param handler
 716             Specifies the event handler you want to use.
 717         @param id
 718             The id of socket event.
 719
 720         @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
 721     */
 722     void SetEventHandler(wxEvtHandler& handler, int id = -1);
 723
 724     /**
 725         Use SetFlags to customize IO operation for this socket.
 726         The @a flags parameter may be a combination of flags ORed together.
 727         The following flags can be used:
 728
 729         @b wxSOCKET_NONE
 730
 731         Normal functionality.
 732
 733         @b wxSOCKET_NOWAIT
 734
 735         Read/write as much data as possible and return immediately.
 736
 737         @b wxSOCKET_WAITALL
 738
 739         Wait for all required data to be read/written unless an error occurs.
 740
 741         @b wxSOCKET_BLOCK
 742
 743         Block the GUI (do not yield) while reading/writing data.
 744
 745         @b wxSOCKET_REUSEADDR
 746
 747         Allows the use of an in-use port (wxServerSocket only)
 748
 749         @b wxSOCKET_BROADCAST
 750
 751         Switches the socket to broadcast mode
 752
 753         @b wxSOCKET_NOBIND
 754
 755         Stops the socket from being bound to a specific adapter (normally used in
 756         conjunction with @b wxSOCKET_BROADCAST)
 757
 758         A brief overview on how to use these flags follows.
 759         If no flag is specified (this is the same as @b wxSOCKET_NONE),
 760         IO calls will return after some data has been read or written, even
 761         when the transfer might not be complete. This is the same as issuing
 762         exactly one blocking low-level call to recv() or send(). Note
 763         that @e blocking here refers to when the function returns, not
 764         to whether the GUI blocks during this time.
 765         If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
 766         Read operations will retrieve only available data. Write operations will
 767         write as much data as possible, depending on how much space is available
 768         in the output buffer. This is the same as issuing exactly one nonblocking
 769         low-level call to recv() or send(). Note that @e nonblocking here
 770         refers to when the function returns, not to whether the GUI blocks during
 771         this time.
 772         If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
 773         the data has been read or written (or until an error occurs), blocking if
 774         necessary, and issuing several low level calls if necessary. This is the
 775         same as having a loop which makes as many blocking low-level calls to
 776         recv() or send() as needed so as to transfer all the data. Note
 777         that @e blocking here refers to when the function returns, not
 778         to whether the GUI blocks during this time.
 779         The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
 780         IO operations. If this flag is specified, the socket will not yield
 781         during IO calls, so the GUI will remain blocked until the operation
 782         completes. If it is not used, then the application must take extra
 783         care to avoid unwanted reentrance.
 784         The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard
 785         setsockopt() flag. This flag allows the socket to bind to a port that is
 786         already in use.
 787         This is mostly used on UNIX-based systems to allow rapid starting and stopping
 788         of a server -
 789         otherwise you may have to wait several minutes for the port to become available.
 790         wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
 791         particular local port
 792         for an outgoing connection.
 793         This option can have surprising platform dependent behavior, so check the
 794         documentation for
 795         your platform's implementation of setsockopt(). Note that on BSD-based systems
 796         (e.g. Mac OS X),
 797         use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to
 798         be consistent
 799         with Windows.
 800         The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard
 801         setsockopt() flag. This flag allows the socket to use the broadcast address,
 802         and is generally
 803         used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress.
 804         So:
 805         @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
 806         @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
 807         read or write ANY data.
 808         @b wxSOCKET_WAITALL will only return when it has read or written ALL
 809         the data.
 810         @b wxSOCKET_BLOCK has nothing to do with the previous flags and
 811         it controls whether the GUI blocks.
 812         @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
 813         reusing local addresses/ports.
 814     */
 815     void SetFlags(wxSocketFlags flags);
 816
 817     /**
 818         This function allows you to set the local address and port,
 819         useful when an application needs to reuse a particular port. When
 820         a local port is set for a wxSocketClient,
 821         @b bind will be called before @b connect.
 822     */
 823     bool SetLocal(wxIPV4address& local);
 824
 825     /**
 826         SetNotify specifies which socket events are to be sent to the event handler.
 827         The @a flags parameter may be combination of flags ORed together. The
 828         following flags can be used:
 829
 830         @b wxSOCKET_INPUT_FLAG
 831
 832         to receive wxSOCKET_INPUT
 833
 834         @b wxSOCKET_OUTPUT_FLAG
 835
 836         to receive wxSOCKET_OUTPUT
 837
 838         @b wxSOCKET_CONNECTION_FLAG
 839
 840         to receive wxSOCKET_CONNECTION
 841
 842         @b wxSOCKET_LOST_FLAG
 843
 844         to receive wxSOCKET_LOST
 845
 846         For example:
 847
 848         In this example, the user will be notified about incoming socket data and
 849         whenever the connection is closed.
 850         For more information on socket events see @ref overview_wxsocketbase "wxSocket
 851         events".
 852     */
 853     void SetNotify(wxSocketEventFlags flags);
 854
 855     /**
 856         This function sets the default socket timeout in seconds. This timeout
 857         applies to all IO calls, and also to the Wait() family
 858         of functions if you don't specify a wait interval. Initially, the default
 859         timeout is 10 minutes.
 860     */
 861     void SetTimeout(int seconds);
 862
 863     /**
 864         Functions to retrieve current state and miscellaneous info.
 865         Error()
 866
 867         GetLocal()
 868
 869         GetPeer()
 870         IsConnected()
 871
 872         IsData()
 873
 874         IsDisconnected()
 875
 876         LastCount()
 877
 878         LastError()
 879
 880         IsOk()
 881
 882         SaveState()
 883
 884         RestoreState()
 885     */
 886
 887
 888     /**
 889         This function unreads a buffer. That is, the data in the buffer is put back
 890         in the incoming queue. This function is not affected by wxSocket flags.
 891         If you use LastCount(), it will always return @e nbytes.
 892         If you use Error(), it will always return @false.
 893
 894         @param buffer
 895             Buffer to be unread.
 896         @param nbytes
 897             Number of bytes.
 898
 899         @return Returns a reference to the current object.
 900
 901         @see Error(), LastCount(), LastError()
 902     */
 903     wxSocketBase Unread(const void* buffer, wxUint32 nbytes);
 904
 905     /**
 906         This function waits until any of the following conditions is @true:
 907
 908          The socket becomes readable.
 909          The socket becomes writable.
 910          An ongoing connection request has completed (wxSocketClient only)
 911          An incoming connection request has arrived (wxSocketServer only)
 912          The connection has been closed.
 913         Note that it is recommended to use the individual Wait functions
 914         to wait for the required condition, instead of this one.
 915
 916         @param seconds
 917             Number of seconds to wait.
 918             If -1, it will wait for the default timeout,
 919             as set with SetTimeout.
 920         @param millisecond
 921             Number of milliseconds to wait.
 922
 923         @return Returns @true when any of the above conditions is satisfied,
 924                  @false if the timeout was reached.
 925
 926         @see InterruptWait(), wxSocketServer::WaitForAccept,
 927              WaitForLost(), WaitForRead(),
 928              WaitForWrite(), wxSocketClient::WaitOnConnect
 929     */
 930     bool Wait(long seconds = -1, long millisecond = 0);
 931
 932     /**
 933         This function waits until the connection is lost. This may happen if
 934         the peer gracefully closes the connection or if the connection breaks.
 935
 936         @param seconds
 937             Number of seconds to wait.
 938             If -1, it will wait for the default timeout,
 939             as set with SetTimeout.
 940         @param millisecond
 941             Number of milliseconds to wait.
 942
 943         @return Returns @true if the connection was lost, @false if the timeout
 944                  was reached.
 945
 946         @see InterruptWait(), Wait()
 947     */
 948     bool WaitForLost(long seconds = -1, long millisecond = 0);
 949
 950     /**
 951         This function waits until the socket is readable. This might mean that
 952         queued data is available for reading or, for streamed sockets, that
 953         the connection has been closed, so that a read operation will complete
 954         immediately without blocking (unless the @b wxSOCKET_WAITALL flag
 955         is set, in which case the operation might still block).
 956
 957         @param seconds
 958             Number of seconds to wait.
 959             If -1, it will wait for the default timeout,
 960             as set with SetTimeout.
 961         @param millisecond
 962             Number of milliseconds to wait.
 963
 964         @return Returns @true if the socket becomes readable, @false on timeout.
 965
 966         @see InterruptWait(), Wait()
 967     */
 968     bool WaitForRead(long seconds = -1, long millisecond = 0);
 969
 970     /**
 971         This function waits until the socket becomes writable. This might mean that
 972         the socket is ready to send new data, or for streamed sockets, that the
 973         connection has been closed, so that a write operation is guaranteed to
 974         complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
 975         in which case the operation might still block).
 976
 977         @param seconds
 978             Number of seconds to wait.
 979             If -1, it will wait for the default timeout,
 980             as set with SetTimeout.
 981         @param millisecond
 982             Number of milliseconds to wait.
 983
 984         @return Returns @true if the socket becomes writable, @false on timeout.
 985
 986         @see InterruptWait(), Wait()
 987     */
 988     bool WaitForWrite(long seconds = -1, long millisecond = 0);
 989
 990     /**
 991         This function writes a buffer of @a nbytes bytes to the socket.
 992         Use LastCount() to verify the number of bytes actually written.
 993         Use Error() to determine if the operation succeeded.
 994
 995         @param buffer
 996             Buffer with the data to be sent.
 997         @param nbytes
 998             Number of bytes.
 999
1000         @return Returns a reference to the current object.
1001
1002         @see Error(), LastError(), LastCount(),
1003              SetFlags()
1004     */
1005     wxSocketBase Write(const void* buffer, wxUint32 nbytes);
1006
1007     /**
1008         This function writes a buffer of @a nbytes bytes from the socket, but it
1009         writes a short header before so that ReadMsg()
1010         knows how much data should it actually read. So, a buffer sent with WriteMsg
1011         @b must be read with ReadMsg. This function always waits for the entire
1012         buffer to be sent, unless an error occurs.
1013         Use LastCount() to verify the number of bytes actually written.
1014         Use Error() to determine if the operation succeeded.
1015
1016         @param buffer
1017             Buffer with the data to be sent.
1018         @param nbytes
1019             Number of bytes to send.
1020
1021         @return Returns a reference to the current object.
1022     */
1023     wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes);
1024 };
1025
1026
1027
1028 /**
1029     @class wxDatagramSocket
1030     @wxheader{socket.h}
1031
1032
1033     @library{wxnet}
1034     @category{FIXME}
1035
1036     @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount,
1037     wxSocketBase::SetFlags,
1038 */
1039 class wxDatagramSocket : public wxSocketBase
1040 {
1041 public:
1042     /**
1043         Constructor.
1044
1045         @param flags
1046             Socket flags (See wxSocketBase::SetFlags)
1047     */
1048     wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE);
1049
1050     /**
1051         Destructor. Please see wxSocketBase::Destroy.
1052     */
1053     ~wxDatagramSocket();
1054
1055     /**
1056         This function reads a buffer of @a nbytes bytes from the socket.
1057         Use wxSocketBase::LastCount to verify the number of bytes actually read.
1058         Use wxSocketBase::Error to determine if the operation succeeded.
1059
1060         @param address
1061             Any address - will be overwritten with the address of the peer that sent
1062         that data.
1063         @param buffer
1064             Buffer where to put read data.
1065         @param nbytes
1066             Number of bytes.
1067
1068         @return Returns a reference to the current object, and the address of
1069                  the peer that sent the data on address param.
1070
1071         @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount,
1072              wxSocketBase::SetFlags,
1073     */
1074     wxDatagramSocket ReceiveFrom(wxSockAddress& address,
1075                                  void* buffer,
1076                                  wxUint32 nbytes);
1077
1078     /**
1079         This function writes a buffer of @a nbytes bytes to the socket.
1080         Use wxSocketBase::LastCount to verify the number of bytes actually wrote.
1081         Use wxSocketBase::Error to determine if the operation succeeded.
1082
1083         @param address
1084             The address of the destination peer for this data.
1085         @param buffer
1086             Buffer where read data is.
1087         @param nbytes
1088             Number of bytes.
1089
1090         @return Returns a reference to the current object.
1091     */
1092     wxDatagramSocket SendTo(const wxSockAddress& address,
1093                             const void* buffer,
1094                             wxUint32 nbytes);
1095 };
1096