interface/wx/socket.h

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