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