interface/wx/socket.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        socket.h
   3 // Purpose:     interface of wxIP*address, wxSocket* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxIPV4address
  11
  12     A class for working with IPv4 network addresses.
  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.
  22
  23         Whenever possible, use this function instead of LocalHost(),
  24         as this correctly handles multi-homed hosts and avoids other small
  25         problems. Internally, this is the same as setting the IP address
  26         to @b INADDR_ANY.
  27
  28         @return @true on success, @false if something went wrong.
  29     */
  30     bool AnyAddress();
  31
  32     /**
  33         Set the address to hostname, which can be a host name or an IP-style address
  34         in dot notation(<tt>a.b.c.d</tt>).
  35
  36         @return @true on success, @false if something goes wrong (invalid
  37                 hostname or invalid IP address).
  38     */
  39     bool Hostname(const wxString& hostname);
  40
  41     /**
  42         Returns the hostname which matches the IP address.
  43     */
  44     virtual wxString Hostname() const;
  45
  46     /**
  47         Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
  48     */
  49     virtual wxString IPAddress() const;
  50
  51     /**
  52         Set address to localhost (127.0.0.1).
  53
  54         Whenever possible, use AnyAddress() instead of this one, as that one will
  55         correctly handle multi-homed hosts and avoid other small problems.
  56
  57         @return @true on success, @false if something went wrong.
  58     */
  59     bool LocalHost();
  60
  61     /**
  62         Set the port to that corresponding to the specified @a service.
  63
  64         @return @true on success, @false if something goes wrong (invalid @a service).
  65     */
  66     bool Service(const wxString& service);
  67
  68     /**
  69         Set the port to that corresponding to the specified @a service.
  70
  71         @return @true on success, @false if something goes wrong (invalid @a service).
  72     */
  73     bool Service(unsigned short service) = 0;
  74
  75     /**
  76         Returns the current service.
  77     */
  78     unsigned short Service() const = 0;
  79 };
  80
  81
  82
  83 /**
  84     @class wxSocketServer
  85
  86     @todo describe me.
  87
  88     @library{wxnet}
  89     @category{net}
  90 */
  91 class wxSocketServer : public wxSocketBase
  92 {
  93 public:
  94     /**
  95         Constructs a new server and tries to bind to the specified @e address.
  96
  97         Before trying to accept new connections, remember to test whether it succeeded
  98         with wxSocketBase:IsOk().
  99
 100         @param address
 101             Specifies the local address for the server (e.g. port number).
 102         @param flags
 103             Socket flags (See wxSocketBase::SetFlags()).
 104     */
 105     wxSocketServer(const wxSockAddress& address,
 106                    wxSocketFlags flags = wxSOCKET_NONE);
 107
 108     /**
 109         Destructor (it doesn't close the accepted connections).
 110     */
 111     virtual ~wxSocketServer();
 112
 113     /**
 114         Accepts an incoming connection request, and creates a new wxSocketBase
 115         object which represents the server-side of the connection.
 116
 117         If @a wait is @true and there are no pending connections to be
 118         accepted, it will wait for the next incoming connection to
 119         arrive.
 120
 121         @warning: This method will block the GUI.
 122
 123         If @a wait is @false, it will try to accept a pending connection
 124         if there is one, but it will always return immediately without blocking
 125         the GUI. If you want to use Accept() in this way, you can either check for
 126         incoming connections with WaitForAccept() or catch @b wxSOCKET_CONNECTION events,
 127         then call Accept() once you know that there is an incoming connection waiting
 128         to be accepted.
 129
 130         @return Returns an opened socket connection, or @NULL if an error
 131                 occurred or if the wait parameter was @false and there
 132                 were no pending connections.
 133
 134         @see WaitForAccept(), wxSocketBase::SetNotify(),
 135              wxSocketBase::Notify(), AcceptWith()
 136     */
 137     wxSocketBase* Accept(bool wait = true);
 138
 139     /**
 140         Accept an incoming connection using the specified socket object.
 141
 142         @param socket
 143             Socket to be initialized
 144         @param wait
 145             See Accept() for more info.
 146
 147         @return Returns @true on success, or @false if an error occurred or
 148                 if the wait parameter was @false and there were no pending
 149                 connections.
 150
 151         @see WaitForAccept(), wxSocketBase::SetNotify(),
 152              wxSocketBase::Notify(), Accept()
 153     */
 154     bool AcceptWith(wxSocketBase& socket, bool wait = true);
 155
 156     /**
 157         Wait for an incoming connection.
 158
 159         Use it if you want to call Accept() or AcceptWith() with @e wait set
 160         to @false, to detect when an incoming connection is waiting to be accepted.
 161
 162         @param seconds
 163             Number of seconds to wait. If -1, it will wait for the default
 164             timeout, as set with wxSocketBase::SetTimeout().
 165         @param millisecond
 166             Number of milliseconds to wait.
 167
 168         @return @true if an incoming connection arrived, @false if the timeout
 169                 elapsed.
 170
 171         @see Accept(), AcceptWith(), wxSocketBase::InterruptWait()
 172     */
 173     bool WaitForAccept(long seconds = -1, long millisecond = 0);
 174 };
 175
 176
 177
 178 /**
 179     @class wxIPaddress
 180
 181     wxIPaddress is an abstract base class for all internet protocol address
 182     objects. Currently, only wxIPV4address is implemented. An experimental
 183     implementation for IPV6, wxIPV6address, is being developed.
 184
 185     @library{wxbase}
 186     @category{net}
 187 */
 188 class wxIPaddress : public wxSockAddress
 189 {
 190 public:
 191     /**
 192         Internally, this is the same as setting the IP address to @b INADDR_ANY.
 193
 194         On IPV4 implementations, 0.0.0.0
 195
 196         On IPV6 implementations, ::
 197
 198         @return @true on success, @false if something went wrong.
 199     */
 200     virtual bool AnyAddress() = 0;
 201
 202     /**
 203         Internally, this is the same as setting the IP address to @b INADDR_BROADCAST.
 204
 205         On IPV4 implementations, 255.255.255.255
 206
 207         @return @true on success, @false if something went wrong.
 208     */
 209     virtual bool BroadcastAddress() = 0;
 210
 211     /**
 212         Set the address to hostname, which can be a host name or an IP-style address
 213         in a format dependent on implementation.
 214
 215         @return @true on success, @false if something goes wrong (invalid
 216                 hostname or invalid IP address).
 217     */
 218     virtual bool Hostname(const wxString& hostname) = 0;
 219
 220     /**
 221         Returns the hostname which matches the IP address.
 222     */
 223     virtual wxString Hostname() const = 0;
 224
 225     /**
 226         Returns a wxString containing the IP address.
 227     */
 228     virtual wxString IPAddress() const = 0;
 229
 230     /**
 231         Determines if current address is set to localhost.
 232
 233         @return @true if address is localhost, @false if internet address.
 234     */
 235     virtual bool IsLocalHost() const = 0;
 236
 237     /**
 238         Set address to localhost.
 239
 240         On IPV4 implementations, 127.0.0.1
 241
 242         On IPV6 implementations, ::1
 243
 244         @return @true on success, @false if something went wrong.
 245     */
 246     virtual bool LocalHost() = 0;
 247
 248     /**
 249         Set the port to that corresponding to the specified service.
 250
 251         @return @true on success, @false if something goes wrong (invalid @a service).
 252     */
 253     virtual bool Service(const wxString& service) = 0;
 254
 255     /**
 256         Set the port to that corresponding to the specified service.
 257
 258         @return @true on success, @false if something goes wrong (invalid @a service).
 259     */
 260     virtual bool Service(unsigned short service) = 0;
 261
 262     /**
 263         Returns the current service.
 264     */
 265     virtual unsigned short Service() const = 0;
 266 };
 267
 268
 269
 270 /**
 271     @class wxSocketClient
 272
 273     @todo describe me.
 274
 275     @library{wxnet}
 276     @category{net}
 277 */
 278 class wxSocketClient : public wxSocketBase
 279 {
 280 public:
 281     /**
 282         Constructor.
 283
 284         @param flags
 285             Socket flags (See wxSocketBase::SetFlags())
 286     */
 287     wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE);
 288
 289     /**
 290         Destructor. Please see wxSocketBase::Destroy().
 291     */
 292     virtual ~wxSocketClient();
 293
 294     /**
 295         Connects to a server using the specified address.
 296
 297         If @a wait is @true, Connect() will wait until the connection
 298         completes.
 299
 300         @warning: This method will block the GUI.
 301
 302         If @a wait is @false, Connect() will try to establish the connection
 303         and return immediately, without blocking the GUI. When used this way,
 304         even if Connect() returns @false, the connection request can be
 305         completed later. To detect this, use WaitOnConnect(), or catch
 306         @b wxSOCKET_CONNECTION events (for successful establishment) and
 307         @b wxSOCKET_LOST events (for connection failure).
 308
 309         @param address
 310             Address of the server.
 311         @param wait
 312             If @true, waits for the connection to complete.
 313
 314         @return @true if the connection is established and no error occurs.
 315                 If @a wait was true, and Connect() returns @false, an error
 316                 occurred and the connection failed.
 317                 If @a wait was @false, and Connect() returns @false, you should
 318                 still be prepared to handle the completion of this connection request,
 319                 either with WaitOnConnect() or by watching wxSOCKET_CONNECTION
 320                 and wxSOCKET_LOST events.
 321
 322         @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
 323     */
 324     virtual bool Connect(const wxSockAddress& address, bool wait = true);
 325
 326     /**
 327         Connects to a server using the specified address.
 328
 329         If @a wait is @true, Connect() will wait until the connection
 330         completes. @b Warning: This will block the GUI.
 331
 332         If @a wait is @false, Connect() will try to establish the connection
 333         and return immediately, without blocking the GUI. When used this way,
 334         even if Connect() returns @false, the connection request can be
 335         completed later. To detect this, use WaitOnConnect(), or catch
 336         @b wxSOCKET_CONNECTION events (for successful establishment) and
 337         @b wxSOCKET_LOST events (for connection failure).
 338
 339         @param address
 340             Address of the server.
 341         @param local
 342             Bind to the specified local address and port before connecting.
 343             The local address and port can also be set using SetLocal(),
 344             and then using the 2-parameter Connect() method.
 345         @param wait
 346             If @true, waits for the connection to complete.
 347
 348         @return @true if the connection is established and no error occurs.
 349                 If @a wait was true, and Connect() returns @false, an error
 350                 occurred and the connection failed.
 351                 If @a wait was @false, and Connect() returns @false, you should
 352                 still be prepared to handle the completion of this connection request,
 353                 either with WaitOnConnect() or by watching wxSOCKET_CONNECTION
 354                 and wxSOCKET_LOST events.
 355
 356         @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
 357     */
 358     bool Connect(const wxSockAddress& address, const wxSockAddress& local,
 359                  bool wait = true);
 360
 361     /**
 362         Wait until a connection request completes, or until the specified timeout
 363         elapses. Use this function after issuing a call to Connect() with
 364         @e wait set to @false.
 365
 366         @param seconds
 367             Number of seconds to wait.
 368             If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout().
 369         @param milliseconds
 370             Number of milliseconds to wait.
 371
 372         @return
 373             WaitOnConnect() returns @true if the connection request completes.
 374             This does not necessarily mean that the connection was
 375             successfully established; it might also happen that the
 376             connection was refused by the peer. Use wxSocketBase::IsConnected()
 377             to distinguish between these two situations.
 378             @n @n If the timeout elapses, WaitOnConnect() returns @false.
 379             @n @n These semantics allow code like this:
 380             @code
 381             // Issue the connection request
 382             client->Connect(addr, false);
 383
 384             // Wait until the request completes or until we decide to give up
 385             bool waitmore = true;
 386             while ( !client->WaitOnConnect(seconds, millis) && waitmore )
 387             {
 388                 // possibly give some feedback to the user,
 389                 // and update waitmore as needed.
 390             }
 391             bool success = client->IsConnected();
 392             @endcode
 393     */
 394     bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
 395 };
 396
 397
 398
 399 /**
 400     @class wxSockAddress
 401
 402     You are unlikely to need to use this class: only wxSocketBase uses it.
 403
 404     @library{wxbase}
 405     @category{net}
 406
 407     @see wxSocketBase, wxIPaddress, wxIPV4address
 408 */
 409 class wxSockAddress : public wxObject
 410 {
 411 public:
 412     /**
 413         Default constructor.
 414     */
 415     wxSockAddress();
 416
 417     /**
 418         Default destructor.
 419     */
 420     virtual ~wxSockAddress();
 421
 422     /**
 423         Delete all informations about the address.
 424     */
 425     virtual void Clear();
 426
 427     /**
 428         Returns the length of the socket address.
 429     */
 430     int SockAddrLen();
 431 };
 432
 433
 434
 435 /**
 436     @class wxSocketEvent
 437
 438     This event class contains information about socket events.
 439
 440     @beginEventTable{wxSocketEvent}
 441     @event{EVT_SOCKET(id, func)}
 442            Process a socket event, supplying the member function.
 443     @endEventTable
 444
 445     @library{wxnet}
 446     @category{net}
 447
 448     @see wxSocketBase, wxSocketClient, wxSocketServer
 449 */
 450 class wxSocketEvent : public wxEvent
 451 {
 452 public:
 453     /**
 454         Constructor.
 455     */
 456     wxSocketEvent(int id = 0);
 457
 458     /**
 459         Gets the client data of the socket which generated this event, as
 460         set with wxSocketBase::SetClientData().
 461     */
 462     void* GetClientData() const;
 463
 464     /**
 465         Returns the socket object to which this event refers to.
 466         This makes it possible to use the same event handler for different sockets.
 467     */
 468     wxSocketBase* GetSocket() const;
 469
 470     /**
 471         Returns the socket event type.
 472     */
 473     wxSocketNotify GetSocketEvent() const;
 474 };
 475
 476
 477 /**
 478     wxSocket error return values.
 479 */
 480 enum wxSocketError
 481 {
 482     wxSOCKET_NOERROR,       ///< No error happened.
 483     wxSOCKET_INVOP,         ///< Invalid operation.
 484     wxSOCKET_IOERR,         ///< Input/Output error.
 485     wxSOCKET_INVADDR,       ///< Invalid address passed to wxSocket.
 486     wxSOCKET_INVSOCK,       ///< Invalid socket (uninitialized).
 487     wxSOCKET_NOHOST,        ///< No corresponding host.
 488     wxSOCKET_INVPORT,       ///< Invalid port.
 489     wxSOCKET_WOULDBLOCK,    ///< The socket is non-blocking and the operation would block.
 490     wxSOCKET_TIMEDOUT,      ///< The timeout for this operation expired.
 491     wxSOCKET_MEMERR         ///< Memory exhausted.
 492 };
 493
 494
 495 /**
 496     @anchor wxSocketEventFlags
 497
 498     wxSocket Event Flags.
 499
 500     A brief note on how to use these events:
 501
 502     The @b wxSOCKET_INPUT event will be issued whenever there is data available
 503     for reading. This will be the case if the input queue was empty and new data
 504     arrives, or if the application has read some data yet there is still more data
 505     available. This means that the application does not need to read all available
 506     data in response to a @b wxSOCKET_INPUT event, as more events will be produced
 507     as necessary.
 508
 509     The @b wxSOCKET_OUTPUT event is issued when a socket is first connected with
 510     Connect() or accepted with Accept(). After that, new events will be generated
 511     only after an output operation fails with @b wxSOCKET_WOULDBLOCK and buffer space
 512     becomes available again. This means that the application should assume that it can
 513     write data to the socket until an @b wxSOCKET_WOULDBLOCK error occurs; after this,
 514     whenever the socket becomes writable again the application will be notified with
 515     another @b wxSOCKET_OUTPUT event.
 516
 517     The @b wxSOCKET_CONNECTION event is issued when a delayed connection request completes
 518     successfully (client) or when a new connection arrives at the incoming queue (server).
 519
 520     The @b wxSOCKET_LOST event is issued when a close indication is received for the socket.
 521     This means that the connection broke down or that it was closed by the peer. Also, this
 522     event will be issued if a connection request fails.
 523 */
 524 enum wxSocketEventFlags
 525 {
 526     wxSOCKET_INPUT,         ///< There is data available for reading.
 527     wxSOCKET_OUTPUT,        ///< The socket is ready to be written to.
 528     wxSOCKET_CONNECTION,    ///< Incoming connection request (server), or
 529                             ///< successful connection establishment (client).
 530     wxSOCKET_LOST           ///< The connection has been closed.
 531 };
 532
 533
 534 /**
 535     @anchor wxSocketFlags
 536
 537     wxSocket Flags.
 538
 539     A brief overview on how to use these flags follows.
 540
 541     If no flag is specified (this is the same as @b wxSOCKET_NONE),
 542     IO calls will return after some data has been read or written, even
 543     when the transfer might not be complete. This is the same as issuing
 544     exactly one blocking low-level call to @b recv() or @b send(). Note
 545     that @e blocking here refers to when the function returns, not
 546     to whether the GUI blocks during this time.
 547
 548     If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
 549     Read operations will retrieve only available data. Write operations will
 550     write as much data as possible, depending on how much space is available
 551     in the output buffer. This is the same as issuing exactly one nonblocking
 552     low-level call to @b recv() or @b send(). Note that @e nonblocking here
 553     refers to when the function returns, not to whether the GUI blocks during
 554     this time.
 555
 556     If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
 557     the data has been read or written (or until an error occurs), blocking if
 558     necessary, and issuing several low level calls if necessary. This is the
 559     same as having a loop which makes as many blocking low-level calls to
 560     @b recv() or @b send() as needed so as to transfer all the data. Note
 561     that @e blocking here refers to when the function returns, not
 562     to whether the GUI blocks during this time.
 563
 564     The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
 565     IO operations. If this flag is specified, the socket will not yield
 566     during IO calls, so the GUI will remain blocked until the operation
 567     completes. If it is not used, then the application must take extra
 568     care to avoid unwanted reentrance.
 569
 570     The @b wxSOCKET_REUSEADDR flag controls the use of the @b SO_REUSEADDR standard
 571     @b setsockopt() flag. This flag allows the socket to bind to a port that is
 572     already in use. This is mostly used on UNIX-based systems to allow rapid starting
 573     and stopping of a server, otherwise you may have to wait several minutes for the
 574     port to become available.
 575
 576     @b wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
 577     particular local port for an outgoing connection.
 578     This option can have surprising platform dependent behavior, so check the
 579     documentation for your platform's implementation of setsockopt().
 580
 581     Note that on BSD-based systems(e.g. Mac OS X), use of
 582     @b wxSOCKET_REUSEADDR implies @b SO_REUSEPORT in addition to
 583     @b SO_REUSEADDR to be consistent with Windows.
 584
 585     The @b wxSOCKET_BROADCAST flag controls the use of the @b SO_BROADCAST standard
 586     @b setsockopt() flag. This flag allows the socket to use the broadcast address,
 587     and is generally used in conjunction with @b wxSOCKET_NOBIND and
 588     wxIPaddress::BroadcastAddress().
 589
 590     So:
 591     - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
 592     - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
 593       read or write ANY data.
 594     - @b wxSOCKET_WAITALL will only return when it has read or written ALL
 595       the data.
 596     - @b wxSOCKET_BLOCK has nothing to do with the previous flags and
 597       it controls whether the GUI blocks.
 598     - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
 599       reusing local addresses/ports.
 600 */
 601 enum
 602 {
 603     wxSOCKET_NONE = 0,      ///< Normal functionality.
 604     wxSOCKET_NOWAIT = 1,    ///< Read/write as much data as possible and return immediately.
 605     wxSOCKET_WAITALL = 2,   ///< Wait for all required data to be read/written unless an error occurs.
 606     wxSOCKET_BLOCK = 4,     ///< Block the GUI (do not yield) while reading/writing data.
 607     wxSOCKET_REUSEADDR = 8, ///< Allows the use of an in-use port (wxServerSocket only)
 608     wxSOCKET_BROADCAST = 16, ///< Switches the socket to broadcast mode
 609     wxSOCKET_NOBIND = 32    ///< Stops the socket from being bound to a specific
 610                             ///< adapter (normally used in conjunction with
 611                             ///< @b wxSOCKET_BROADCAST)
 612 };
 613
 614
 615 /**
 616     @class wxSocketBase
 617
 618     wxSocketBase is the base class for all socket-related objects, and it
 619     defines all basic IO functionality.
 620
 621     @note
 622     When using wxSocket from multiple threads, even implicitly (e.g. by using
 623     wxFTP or wxHTTP in another thread) you must initialize the sockets from the
 624     main thread by calling Initialize() before creating the other ones.
 625
 626     @beginEventTable{wxSocketEvent}
 627     @event{EVT_SOCKET(id, func)}
 628         Process a @c wxEVT_SOCKET event.
 629         See @ref wxSocketEventFlags and @ref wxSocketFlags for more info.
 630     @endEventTable
 631
 632     @library{wxnet}
 633     @category{net}
 634
 635     @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
 636          @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
 637 */
 638 class wxSocketBase : public wxObject
 639 {
 640 public:
 641
 642     /**
 643         @name Construction and Destruction
 644     */
 645     //@{
 646
 647     /**
 648         Default constructor.
 649
 650         Don't use it directly; instead, use wxSocketClient to construct a socket client,
 651         or wxSocketServer to construct a socket server.
 652     */
 653     wxSocketBase();
 654
 655     /**
 656         Destructor.
 657
 658         Do not destroy a socket using the delete operator directly;
 659         use Destroy() instead. Also, do not create socket objects in the stack.
 660     */
 661     ~wxSocketBase();
 662
 663     /**
 664         Destroys the socket safely.
 665
 666         Use this function instead of the delete operator, since otherwise socket events
 667         could reach the application even after the socket has been destroyed. To prevent
 668         this problem, this function appends the wxSocket to a list of object to be deleted
 669         on idle time, after all events have been processed. For the same reason, you should
 670         avoid creating socket objects in the stack.
 671
 672         Destroy() calls Close() automatically.
 673
 674         @return Always @true.
 675     */
 676     bool Destroy();
 677
 678     /**
 679         Perform the initialization needed in order to use the sockets.
 680
 681         This function is called from wxSocket constructor implicitly and so
 682         normally doesn't need to be called explicitly. There is however one
 683         important exception: as this function must be called from the main
 684         (UI) thread, if you use wxSocket from multiple threads you must call
 685         Initialize() from the main thread before creating wxSocket objects in
 686         the other ones.
 687
 688         It is safe to call this function multiple times (only the first call
 689         does anything) but you must call Shutdown() exactly once for every call
 690         to Initialize().
 691
 692         @return
 693             @true if the sockets can be used, @false if the initialization
 694             failed and sockets are not available at all.
 695      */
 696     static bool Initialize();
 697
 698     /**
 699         Shut down the sockets.
 700
 701         This function undoes the call to Initialize() and must be called after
 702         every successful call to Initialize().
 703      */
 704     static void Shutdown();
 705
 706     //@}
 707
 708
 709     /**
 710         @name Socket State
 711     */
 712     //@{
 713
 714     /**
 715         Returns @true if an error occurred in the last IO operation.
 716
 717         Use this function to check for an error condition after one of the
 718         following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg().
 719     */
 720     bool Error() const;
 721
 722     /**
 723         Return the local address of the socket.
 724
 725         @return @true if no error happened, @false otherwise.
 726     */
 727     bool GetLocal(wxSockAddress& addr) const;
 728
 729     /**
 730         Return the peer address field of the socket.
 731
 732         @return @true if no error happened, @false otherwise.
 733     */
 734     bool GetPeer(wxSockAddress& addr) const;
 735
 736     /**
 737         Return the socket timeout in seconds.
 738
 739         The timeout can be set using SetTimeout() and is 10 minutes by default.
 740      */
 741     long GetTimeout() const;
 742
 743     /**
 744         Returns @true if the socket is connected.
 745     */
 746     bool IsConnected() const;
 747
 748     /**
 749         Check if the socket can be currently read or written.
 750
 751         This might mean that queued data is available for reading or, for streamed
 752         sockets, that the connection has been closed, so that a read operation will
 753         complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
 754         is set, in which case the operation might still block).
 755     */
 756     bool IsData() const;
 757
 758     /**
 759         Returns @true if the socket is not connected.
 760     */
 761     bool IsDisconnected() const;
 762
 763     /**
 764         Returns @true if the socket is initialized and ready and @false in other
 765         cases.
 766
 767         @remarks
 768         For wxSocketClient, IsOk() won't return @true unless the client is connected to a server.
 769         For wxSocketServer, IsOk() will return @true if the server could bind to the specified address
 770         and is already listening for new connections.
 771         IsOk() does not check for IO errors; use Error() instead for that purpose.
 772     */
 773     bool IsOk() const;
 774
 775     /**
 776         Returns the number of bytes read or written by the last IO call.
 777
 778         Use this function to get the number of bytes actually transferred
 779         after using one of the following IO calls: Discard(), Peek(), Read(),
 780         ReadMsg(), Unread(), Write(), WriteMsg().
 781     */
 782     wxUint32 LastCount() const;
 783
 784     /**
 785         Returns the last wxSocket error. See @ref wxSocketError .
 786
 787         @note
 788         This function merely returns the last error code,
 789         but it should not be used to determine if an error has occurred (this
 790         is because successful operations do not change the LastError value).
 791         Use Error() first, in order to determine if the last IO call failed.
 792         If this returns @true, use LastError() to discover the cause of the error.
 793     */
 794     wxSocketError LastError() const;
 795
 796     /**
 797         Restore the previous state of the socket, as saved with SaveState().
 798
 799         Calls to SaveState() and RestoreState() can be nested.
 800
 801         @see SaveState()
 802     */
 803     void RestoreState();
 804
 805     /**
 806         Save the current state of the socket in a stack.
 807
 808         Socket state includes flags, as set with SetFlags(), event mask, as set
 809         with SetNotify() and Notify(), user data, as set with SetClientData().
 810         Calls to SaveState and RestoreState can be nested.
 811
 812         @see RestoreState()
 813     */
 814     void SaveState();
 815
 816     //@}
 817
 818
 819     /**
 820         @name Basic I/O
 821
 822         See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
 823     */
 824     //@{
 825
 826     /**
 827         Shut down the socket, disabling further transmission and reception of
 828         data and disable events for the socket and frees the associated system
 829         resources.
 830
 831         Upon socket destruction, Close() is automatically called, so in most cases
 832         you won't need to do it yourself, unless you explicitly want to shut down
 833         the socket, typically to notify the peer that you are closing the connection.
 834
 835         @remarks
 836         Although Close() immediately disables events for the socket, it is possible
 837         that event messages may be waiting in the application's event queue.
 838         The application must therefore be prepared to handle socket event messages even
 839         after calling Close().
 840     */
 841     void Close();
 842
 843     /**
 844         Shuts down the writing end of the socket.
 845
 846         This function simply calls the standard shutdown() function on the
 847         underlying socket, indicating that nothing will be written to this
 848         socket any more.
 849      */
 850     void ShutdownOutput();
 851
 852     /**
 853         Delete all bytes in the incoming queue.
 854
 855         This function always returns immediately and its operation is not
 856         affected by IO flags.
 857
 858         Use LastCount() to verify the number of bytes actually discarded.
 859
 860         If you use Error(), it will always return @false.
 861     */
 862     wxSocketBase& Discard();
 863
 864     /**
 865         Returns current IO flags, as set with SetFlags()
 866     */
 867     wxSocketFlags GetFlags() const;
 868
 869     /**
 870         Use this function to interrupt any wait operation currently in progress.
 871
 872         Note that this is not intended as a regular way to interrupt a Wait call,
 873         but only as an escape mechanism for exceptional situations where it is
 874         absolutely necessary to use it, for example to abort an operation due to
 875         some exception or abnormal problem. InterruptWait is automatically called
 876         when you Close() a socket (and thus also upon
 877         socket destruction), so you don't need to use it in these cases.
 878
 879         @see  Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
 880               wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
 881     */
 882     void InterruptWait();
 883
 884     /**
 885         Peek into the socket by copying the next bytes which would be read by
 886         Read() into the provided buffer.
 887
 888         Peeking a buffer doesn't delete it from the socket input queue, i.e.
 889         calling Read() will return the same data.
 890
 891         Use LastCount() to verify the number of bytes actually peeked.
 892
 893         Use Error() to determine if the operation succeeded.
 894
 895         @param buffer
 896             Buffer where to put peeked data.
 897         @param nbytes
 898             Number of bytes.
 899
 900         @return Returns a reference to the current object.
 901
 902         @remarks
 903             The exact behaviour of Peek() depends on the combination of flags being used.
 904             For a detailed explanation, see SetFlags()
 905
 906         @see Error(), LastError(), LastCount(), SetFlags()
 907     */
 908     wxSocketBase& Peek(void* buffer, wxUint32 nbytes);
 909
 910     /**
 911         Read up to the given number of bytes from the socket.
 912
 913         Use LastCount() to verify the number of bytes actually read.
 914         Use Error() to determine if the operation succeeded.
 915
 916         @param buffer
 917             Buffer where to put read data.
 918         @param nbytes
 919             Number of bytes.
 920
 921         @return Returns a reference to the current object.
 922
 923         @remarks
 924             The exact behaviour of Read() depends on the combination of flags being used.
 925             For a detailed explanation, see SetFlags()
 926
 927         @see Error(), LastError(), LastCount(),
 928              SetFlags()
 929     */
 930     wxSocketBase& Read(void* buffer, wxUint32 nbytes);
 931
 932     /**
 933         Receive a message sent by WriteMsg().
 934
 935         If the buffer passed to the function isn't big enough, the remaining
 936         bytes will be discarded. This function always waits for the buffer to
 937         be entirely filled, unless an error occurs.
 938
 939         Use LastCount() to verify the number of bytes actually read.
 940
 941         Use Error() to determine if the operation succeeded.
 942
 943         @param buffer
 944             Buffer where to put read data.
 945         @param nbytes
 946             Size of the buffer.
 947
 948         @return Returns a reference to the current object.
 949
 950         @remarks
 951             ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
 952             and it will always ignore the @b wxSOCKET_NOWAIT flag.
 953             The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
 954             For a detailed explanation, see SetFlags().
 955
 956         @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
 957     */
 958     wxSocketBase& ReadMsg(void* buffer, wxUint32 nbytes);
 959
 960     /**
 961         Use SetFlags to customize IO operation for this socket.
 962
 963         The @a flags parameter may be a combination of flags ORed together.
 964         Notice that not all combinations of flags affecting the IO calls
 965         (Read() and Write()) make sense, e.g. @b wxSOCKET_NOWAIT can't be
 966         combined with @b wxSOCKET_WAITALL nor with @b wxSOCKET_BLOCK.
 967
 968         The following flags can be used:
 969         @beginFlagTable
 970         @flag{wxSOCKET_NONE}
 971             Default mode: the socket will read some data in the IO calls and
 972             will process events to avoid blocking UI while waiting for the data
 973             to become available.
 974         @flag{wxSOCKET_NOWAIT}
 975             Don't wait for the socket to become ready in IO calls, read as much
 976             data as is available -- potentially 0 bytes -- and return
 977             immediately.
 978         @flag{wxSOCKET_WAITALL}
 979             Don't return before the entire amount of data specified in IO calls
 980             is read or written unless an error occurs. If this flag is not
 981             specified, the IO calls return as soon as any amount of data, even
 982             less than the total number of bytes, is processed.
 983         @flag{wxSOCKET_BLOCK}
 984             Don't process the UI events while waiting for the socket to become
 985             ready. This means that UI will be unresponsive during socket IO.
 986         @flag{wxSOCKET_REUSEADDR}
 987             Allows the use of an in-use port (wxServerSocket only).
 988         @flag{wxSOCKET_BROADCAST}
 989             Switches the socket to broadcast mode.
 990         @flag{wxSOCKET_NOBIND}
 991             Stops the socket from being bound to a specific adapter (normally
 992             used in conjunction with @b wxSOCKET_BROADCAST).
 993         @endFlagTable
 994
 995         For more information on socket events see @ref wxSocketFlags .
 996     */
 997     void SetFlags(wxSocketFlags flags);
 998
 999     /**
1000         Set the local address and port to use.
1001
1002         This function must always be called for the server sockets but may also
1003         be called for client sockets, if it is, @b bind() is called before @b
1004         connect().
1005     */
1006     bool SetLocal(const wxIPV4address& local);
1007
1008     /**
1009         Set the default socket timeout in seconds.
1010
1011         This timeout applies to all IO calls, and also to the Wait() family of
1012         functions if you don't specify a wait interval. Initially, the default
1013         timeout is 10 minutes.
1014     */
1015     void SetTimeout(int seconds);
1016
1017     /**
1018         Put the specified data into the input queue.
1019
1020         The data in the buffer will be returned by the next call to Read().
1021
1022         This function is not affected by wxSocket flags.
1023
1024         If you use LastCount(), it will always return @a nbytes.
1025
1026         If you use Error(), it will always return @false.
1027
1028         @param buffer
1029             Buffer to be unread.
1030         @param nbytes
1031             Number of bytes.
1032
1033         @return Returns a reference to the current object.
1034
1035         @see Error(), LastCount(), LastError()
1036     */
1037     wxSocketBase& Unread(const void* buffer, wxUint32 nbytes);
1038
1039     /**
1040         Wait for any socket event.
1041
1042         Possible socket events are:
1043         @li The socket becomes readable.
1044         @li The socket becomes writable.
1045         @li An ongoing connection request has completed (wxSocketClient only)
1046         @li An incoming connection request has arrived (wxSocketServer only)
1047         @li The connection has been closed.
1048
1049         Note that it is recommended to use the individual @b WaitForXXX()
1050         functions to wait for the required condition, instead of this one.
1051
1052         @param seconds
1053             Number of seconds to wait.
1054             If -1, it will wait for the default timeout,
1055             as set with SetTimeout().
1056         @param millisecond
1057             Number of milliseconds to wait.
1058
1059         @return
1060            @true when any of the above conditions is satisfied or @false if the
1061            timeout was reached.
1062
1063         @see InterruptWait(), wxSocketServer::WaitForAccept(),
1064              WaitForLost(), WaitForRead(),
1065              WaitForWrite(), wxSocketClient::WaitOnConnect()
1066     */
1067     bool Wait(long seconds = -1, long millisecond = 0);
1068
1069     /**
1070         Wait until the connection is lost.
1071
1072         This may happen if the peer gracefully closes the connection or if the
1073         connection breaks.
1074
1075         @param seconds
1076             Number of seconds to wait.
1077             If -1, it will wait for the default timeout,
1078             as set with SetTimeout().
1079         @param millisecond
1080             Number of milliseconds to wait.
1081
1082         @return Returns @true if the connection was lost, @false if the timeout
1083                 was reached.
1084
1085         @see InterruptWait(), Wait()
1086     */
1087     bool WaitForLost(long seconds = -1, long millisecond = 0);
1088
1089     /**
1090         Wait until the socket is readable.
1091
1092         This might mean that queued data is available for reading or, for streamed
1093         sockets, that the connection has been closed, so that a read operation will
1094         complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
1095         is set, in which case the operation might still block).
1096
1097         Notice that this function should not be called if there is already data
1098         available for reading on the socket.
1099
1100         @param seconds
1101             Number of seconds to wait.
1102             If -1, it will wait for the default timeout,
1103             as set with SetTimeout().
1104         @param millisecond
1105             Number of milliseconds to wait.
1106
1107         @return Returns @true if the socket becomes readable, @false on timeout.
1108
1109         @see InterruptWait(), Wait()
1110     */
1111     bool WaitForRead(long seconds = -1, long millisecond = 0);
1112
1113     /**
1114         Wait until the socket becomes writable.
1115
1116         This might mean that the socket is ready to send new data, or for streamed
1117         sockets, that the connection has been closed, so that a write operation is
1118         guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
1119         in which case the operation might still block).
1120
1121         Notice that this function should not be called if the socket is already
1122         writable.
1123
1124         @param seconds
1125             Number of seconds to wait.
1126             If -1, it will wait for the default timeout,
1127             as set with SetTimeout().
1128         @param millisecond
1129             Number of milliseconds to wait.
1130
1131         @return Returns @true if the socket becomes writable, @false on timeout.
1132
1133         @see InterruptWait(), Wait()
1134     */
1135     bool WaitForWrite(long seconds = -1, long millisecond = 0);
1136
1137     /**
1138         Write up to the given number of bytes to the socket.
1139
1140         Use LastCount() to verify the number of bytes actually written.
1141
1142         Use Error() to determine if the operation succeeded.
1143
1144         @param buffer
1145             Buffer with the data to be sent.
1146         @param nbytes
1147             Number of bytes.
1148
1149         @return Returns a reference to the current object.
1150
1151         @remarks
1152
1153         The exact behaviour of Write() depends on the combination of flags being used.
1154         For a detailed explanation, see SetFlags().
1155
1156         @see Error(), LastError(), LastCount(), SetFlags()
1157     */
1158     wxSocketBase& Write(const void* buffer, wxUint32 nbytes);
1159
1160     /**
1161         Sends a buffer which can be read using ReadMsg().
1162
1163         WriteMsg() sends a short header before the data so that ReadMsg()
1164         knows how much data should be actually read.
1165
1166         This function always waits for the entire buffer to be sent, unless an
1167         error occurs.
1168
1169         Use LastCount() to verify the number of bytes actually written.
1170
1171         Use Error() to determine if the operation succeeded.
1172
1173         @param buffer
1174             Buffer with the data to be sent.
1175         @param nbytes
1176             Number of bytes to send.
1177
1178         @return Returns a reference to the current object.
1179
1180         @remarks
1181
1182         WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and
1183         it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of
1184         WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation,
1185         see SetFlags().
1186
1187         @see  Error(), LastError(), LastCount(), SetFlags(), ReadMsg()
1188
1189     */
1190     wxSocketBase& WriteMsg(const void* buffer, wxUint32 nbytes);
1191
1192     //@}
1193
1194
1195     /**
1196         @name Handling Socket Events
1197     */
1198     //@{
1199
1200     /**
1201         Returns a pointer of the client data for this socket, as set with
1202         SetClientData()
1203     */
1204     void* GetClientData() const;
1205
1206     /**
1207         According to the @a notify value, this function enables
1208         or disables socket events. If @a notify is @true, the events
1209         configured with SetNotify() will
1210         be sent to the application. If @a notify is @false; no events
1211         will be sent.
1212     */
1213     void Notify(bool notify);
1214
1215     /**
1216         Sets user-supplied client data for this socket. All socket events will
1217         contain a pointer to this data, which can be retrieved with
1218         the wxSocketEvent::GetClientData() function.
1219     */
1220     void SetClientData(void* data);
1221
1222     /**
1223         Sets an event handler to be called when a socket event occurs. The
1224         handler will be called for those events for which notification is
1225         enabled with SetNotify() and
1226         Notify().
1227
1228         @param handler
1229             Specifies the event handler you want to use.
1230         @param id
1231             The id of socket event.
1232
1233         @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
1234     */
1235     void SetEventHandler(wxEvtHandler& handler, int id = -1);
1236
1237     /**
1238         Specifies which socket events are to be sent to the event handler.
1239         The @a flags parameter may be combination of flags ORed together. The
1240         following flags can be used:
1241
1242         @beginFlagTable
1243         @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT.
1244         @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT.
1245         @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION.
1246         @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST.
1247         @endFlagTable
1248
1249         For example:
1250
1251         @code
1252         sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
1253         sock.Notify(true);
1254         @endcode
1255
1256         In this example, the user will be notified about incoming socket data and
1257         whenever the connection is closed.
1258
1259         For more information on socket events see @ref wxSocketEventFlags .
1260     */
1261     void SetNotify(wxSocketEventFlags flags);
1262
1263     //@}
1264 };
1265
1266
1267
1268 /**
1269     @class wxDatagramSocket
1270
1271     @todo docme
1272
1273     @library{wxnet}
1274     @category{net}
1275 */
1276 class wxDatagramSocket : public wxSocketBase
1277 {
1278 public:
1279     /**
1280         Constructor.
1281
1282         @param addr
1283             The socket address.
1284         @param flags
1285             Socket flags (See wxSocketBase::SetFlags()).
1286     */
1287     wxDatagramSocket(const wxSockAddress& addr,
1288                      wxSocketFlags flags = wxSOCKET_NONE);
1289
1290     /**
1291         Destructor. Please see wxSocketBase::Destroy().
1292     */
1293     virtual ~wxDatagramSocket();
1294
1295     /**
1296         Write a buffer of @a nbytes bytes to the socket.
1297
1298         Use wxSocketBase::LastCount() to verify the number of bytes actually wrote.
1299         Use wxSocketBase::Error() to determine if the operation succeeded.
1300
1301         @param address
1302             The address of the destination peer for this data.
1303         @param buffer
1304             Buffer where read data is.
1305         @param nbytes
1306             Number of bytes.
1307
1308         @return Returns a reference to the current object.
1309
1310         @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
1311     */
1312     wxDatagramSocket& SendTo(const wxSockAddress& address,
1313                              const void* buffer, wxUint32 nbytes);
1314 };
1315