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