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         Returns the pointer to the low-level representation of the address.
 433
 434         This can be used to pass socket address information to a 3rd party
 435         library.
 436
 437         @return
 438             Pointer to a sockaddr-derived struct.
 439     */
 440     const sockaddr *GetAddressData() const;
 441
 442     /**
 443         Returns the length of the buffer retrieved by GetAddressData().
 444
 445         @return
 446             The size of the sockaddr-derived struct corresponding to this
 447             address.
 448     */
 449     int GetAddressDataLen() const;
 450 };
 451
 452
 453
 454 /**
 455     @class wxSocketEvent
 456
 457     This event class contains information about socket events.
 458     This kind of events are sent to the event handler specified with
 459     wxSocketBase::SetEventHandler.
 460
 461     @beginEventTable{wxSocketEvent}
 462     @event{EVT_SOCKET(id, func)}
 463         Process a socket event, supplying the member function.
 464     @endEventTable
 465
 466     @library{wxnet}
 467     @category{net}
 468
 469     @see wxSocketBase, wxSocketClient, wxSocketServer
 470 */
 471 class wxSocketEvent : public wxEvent
 472 {
 473 public:
 474     /**
 475         Constructor.
 476     */
 477     wxSocketEvent(int id = 0);
 478
 479     /**
 480         Gets the client data of the socket which generated this event, as
 481         set with wxSocketBase::SetClientData().
 482     */
 483     void* GetClientData() const;
 484
 485     /**
 486         Returns the socket object to which this event refers to.
 487         This makes it possible to use the same event handler for different sockets.
 488     */
 489     wxSocketBase* GetSocket() const;
 490
 491     /**
 492         Returns the socket event type.
 493     */
 494     wxSocketNotify GetSocketEvent() const;
 495 };
 496
 497
 498 /**
 499     wxSocket error return values.
 500 */
 501 enum wxSocketError
 502 {
 503     wxSOCKET_NOERROR,       ///< No error happened.
 504     wxSOCKET_INVOP,         ///< Invalid operation.
 505     wxSOCKET_IOERR,         ///< Input/Output error.
 506     wxSOCKET_INVADDR,       ///< Invalid address passed to wxSocket.
 507     wxSOCKET_INVSOCK,       ///< Invalid socket (uninitialized).
 508     wxSOCKET_NOHOST,        ///< No corresponding host.
 509     wxSOCKET_INVPORT,       ///< Invalid port.
 510     wxSOCKET_WOULDBLOCK,    ///< The socket is non-blocking and the operation would block.
 511     wxSOCKET_TIMEDOUT,      ///< The timeout for this operation expired.
 512     wxSOCKET_MEMERR         ///< Memory exhausted.
 513 };
 514
 515
 516 /**
 517     @anchor wxSocketEventFlags
 518
 519     wxSocket Event Flags.
 520
 521     A brief note on how to use these events:
 522
 523     The @b wxSOCKET_INPUT event will be issued whenever there is data available
 524     for reading. This will be the case if the input queue was empty and new data
 525     arrives, or if the application has read some data yet there is still more data
 526     available. This means that the application does not need to read all available
 527     data in response to a @b wxSOCKET_INPUT event, as more events will be produced
 528     as necessary.
 529
 530     The @b wxSOCKET_OUTPUT event is issued when a socket is first connected with
 531     Connect() or accepted with Accept(). After that, new events will be generated
 532     only after an output operation fails with @b wxSOCKET_WOULDBLOCK and buffer space
 533     becomes available again. This means that the application should assume that it can
 534     write data to the socket until an @b wxSOCKET_WOULDBLOCK error occurs; after this,
 535     whenever the socket becomes writable again the application will be notified with
 536     another @b wxSOCKET_OUTPUT event.
 537
 538     The @b wxSOCKET_CONNECTION event is issued when a delayed connection request completes
 539     successfully (client) or when a new connection arrives at the incoming queue (server).
 540
 541     The @b wxSOCKET_LOST event is issued when a close indication is received for the socket.
 542     This means that the connection broke down or that it was closed by the peer. Also, this
 543     event will be issued if a connection request fails.
 544 */
 545 enum wxSocketEventFlags
 546 {
 547     wxSOCKET_INPUT,         ///< There is data available for reading.
 548     wxSOCKET_OUTPUT,        ///< The socket is ready to be written to.
 549     wxSOCKET_CONNECTION,    ///< Incoming connection request (server), or
 550                             ///< successful connection establishment (client).
 551     wxSOCKET_LOST           ///< The connection has been closed.
 552 };
 553
 554
 555 /**
 556     @anchor wxSocketFlags
 557
 558     wxSocket Flags.
 559
 560     A brief overview on how to use these flags follows.
 561
 562     If no flag is specified (this is the same as @b wxSOCKET_NONE),
 563     IO calls will return after some data has been read or written, even
 564     when the transfer might not be complete. This is the same as issuing
 565     exactly one blocking low-level call to @b recv() or @b send(). Note
 566     that @e blocking here refers to when the function returns, not
 567     to whether the GUI blocks during this time.
 568
 569     If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
 570     Read operations will retrieve only available data. Write operations will
 571     write as much data as possible, depending on how much space is available
 572     in the output buffer. This is the same as issuing exactly one nonblocking
 573     low-level call to @b recv() or @b send(). Note that @e nonblocking here
 574     refers to when the function returns, not to whether the GUI blocks during
 575     this time.
 576
 577     If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
 578     the data has been read or written (or until an error occurs), blocking if
 579     necessary, and issuing several low level calls if necessary. This is the
 580     same as having a loop which makes as many blocking low-level calls to
 581     @b recv() or @b send() as needed so as to transfer all the data. Note
 582     that @e blocking here refers to when the function returns, not
 583     to whether the GUI blocks during this time.
 584
 585     The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
 586     IO operations. If this flag is specified, the socket will not yield
 587     during IO calls, so the GUI will remain blocked until the operation
 588     completes. If it is not used, then the application must take extra
 589     care to avoid unwanted reentrance.
 590
 591     The @b wxSOCKET_REUSEADDR flag controls the use of the @b SO_REUSEADDR standard
 592     @b setsockopt() flag. This flag allows the socket to bind to a port that is
 593     already in use. This is mostly used on UNIX-based systems to allow rapid starting
 594     and stopping of a server, otherwise you may have to wait several minutes for the
 595     port to become available.
 596
 597     @b wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
 598     particular local port for an outgoing connection.
 599     This option can have surprising platform dependent behavior, so check the
 600     documentation for your platform's implementation of setsockopt().
 601
 602     Note that on BSD-based systems(e.g. Mac OS X), use of
 603     @b wxSOCKET_REUSEADDR implies @b SO_REUSEPORT in addition to
 604     @b SO_REUSEADDR to be consistent with Windows.
 605
 606     The @b wxSOCKET_BROADCAST flag controls the use of the @b SO_BROADCAST standard
 607     @b setsockopt() flag. This flag allows the socket to use the broadcast address,
 608     and is generally used in conjunction with @b wxSOCKET_NOBIND and
 609     wxIPaddress::BroadcastAddress().
 610
 611     So:
 612     - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
 613     - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
 614       read or write ANY data.
 615     - @b wxSOCKET_WAITALL will only return when it has read or written ALL
 616       the data.
 617     - @b wxSOCKET_BLOCK has nothing to do with the previous flags and
 618       it controls whether the GUI blocks.
 619     - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
 620       reusing local addresses/ports.
 621 */
 622 enum
 623 {
 624     wxSOCKET_NONE = 0,      ///< Normal functionality.
 625     wxSOCKET_NOWAIT = 1,    ///< Read/write as much data as possible and return immediately.
 626     wxSOCKET_WAITALL = 2,   ///< Wait for all required data to be read/written unless an error occurs.
 627     wxSOCKET_BLOCK = 4,     ///< Block the GUI (do not yield) while reading/writing data.
 628     wxSOCKET_REUSEADDR = 8, ///< Allows the use of an in-use port.
 629     wxSOCKET_BROADCAST = 16, ///< Switches the socket to broadcast mode
 630     wxSOCKET_NOBIND = 32    ///< Stops the socket from being bound to a specific
 631                             ///< adapter (normally used in conjunction with
 632                             ///< @b wxSOCKET_BROADCAST)
 633 };
 634
 635
 636 /**
 637     @class wxSocketBase
 638
 639     wxSocketBase is the base class for all socket-related objects, and it
 640     defines all basic IO functionality.
 641
 642     @note
 643     When using wxSocket from multiple threads, even implicitly (e.g. by using
 644     wxFTP or wxHTTP in another thread) you must initialize the sockets from the
 645     main thread by calling Initialize() before creating the other ones.
 646
 647     @beginEventEmissionTable{wxSocketEvent}
 648     @event{EVT_SOCKET(id, func)}
 649         Process a @c wxEVT_SOCKET event.
 650         See @ref wxSocketEventFlags and @ref wxSocketFlags for more info.
 651     @endEventTable
 652
 653     @library{wxnet}
 654     @category{net}
 655
 656     @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
 657          @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
 658 */
 659 class wxSocketBase : public wxObject
 660 {
 661 public:
 662
 663     /**
 664         @name Construction and Destruction
 665     */
 666     //@{
 667
 668     /**
 669         Default constructor.
 670
 671         Don't use it directly; instead, use wxSocketClient to construct a socket client,
 672         or wxSocketServer to construct a socket server.
 673     */
 674     wxSocketBase();
 675
 676     /**
 677         Destructor.
 678
 679         Do not destroy a socket using the delete operator directly;
 680         use Destroy() instead. Also, do not create socket objects in the stack.
 681     */
 682     virtual ~wxSocketBase();
 683
 684     /**
 685         Destroys the socket safely.
 686
 687         Use this function instead of the delete operator, since otherwise socket events
 688         could reach the application even after the socket has been destroyed. To prevent
 689         this problem, this function appends the wxSocket to a list of object to be deleted
 690         on idle time, after all events have been processed. For the same reason, you should
 691         avoid creating socket objects in the stack.
 692
 693         Destroy() calls Close() automatically.
 694
 695         @return Always @true.
 696     */
 697     bool Destroy();
 698
 699     /**
 700         Perform the initialization needed in order to use the sockets.
 701
 702         This function is called from wxSocket constructor implicitly and so
 703         normally doesn't need to be called explicitly. There is however one
 704         important exception: as this function must be called from the main
 705         (UI) thread, if you use wxSocket from multiple threads you must call
 706         Initialize() from the main thread before creating wxSocket objects in
 707         the other ones.
 708
 709         It is safe to call this function multiple times (only the first call
 710         does anything) but you must call Shutdown() exactly once for every call
 711         to Initialize().
 712
 713         This function should only be called from the main thread.
 714
 715         @return
 716             @true if the sockets can be used, @false if the initialization
 717             failed and sockets are not available at all.
 718      */
 719     static bool Initialize();
 720
 721     /**
 722         Shut down the sockets.
 723
 724         This function undoes the call to Initialize() and must be called after
 725         every successful call to Initialize().
 726
 727         This function should only be called from the main thread, just as
 728         Initialize().
 729      */
 730     static void Shutdown();
 731
 732     //@}
 733
 734
 735     /**
 736         @name Socket State
 737     */
 738     //@{
 739
 740     /**
 741         Returns @true if an error occurred in the last IO operation.
 742
 743         Use this function to check for an error condition after one of the
 744         following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg().
 745     */
 746     bool Error() const;
 747
 748     /**
 749         Return the local address of the socket.
 750
 751         @return @true if no error happened, @false otherwise.
 752     */
 753     virtual bool GetLocal(wxSockAddress& addr) const;
 754
 755     /**
 756         Return the peer address field of the socket.
 757
 758         @return @true if no error happened, @false otherwise.
 759     */
 760     virtual bool GetPeer(wxSockAddress& addr) const;
 761
 762     /**
 763         Return the socket timeout in seconds.
 764
 765         The timeout can be set using SetTimeout() and is 10 minutes by default.
 766      */
 767     long GetTimeout() const;
 768
 769     /**
 770         Returns @true if the socket is connected.
 771     */
 772     bool IsConnected() const;
 773
 774     /**
 775         Check if the socket can be currently read or written.
 776
 777         This might mean that queued data is available for reading or, for streamed
 778         sockets, that the connection has been closed, so that a read operation will
 779         complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
 780         is set, in which case the operation might still block).
 781     */
 782     bool IsData();
 783
 784     /**
 785         Returns @true if the socket is not connected.
 786     */
 787     bool IsDisconnected() const;
 788
 789     /**
 790         Returns @true if the socket is initialized and ready and @false in other
 791         cases.
 792
 793         @remarks
 794         For wxSocketClient, IsOk() won't return @true unless the client is connected to a server.
 795         For wxSocketServer, IsOk() will return @true if the server could bind to the specified address
 796         and is already listening for new connections.
 797         IsOk() does not check for IO errors; use Error() instead for that purpose.
 798     */
 799     bool IsOk() const;
 800
 801     /**
 802         Returns the number of bytes read or written by the last IO call.
 803
 804         Use this function to get the number of bytes actually transferred
 805         after using one of the following IO calls: Discard(), Peek(), Read(),
 806         ReadMsg(), Unread(), Write(), WriteMsg().
 807     */
 808     wxUint32 LastCount() const;
 809
 810     /**
 811         Returns the last wxSocket error. See @ref wxSocketError .
 812
 813         @note
 814         This function merely returns the last error code,
 815         but it should not be used to determine if an error has occurred (this
 816         is because successful operations do not change the LastError value).
 817         Use Error() first, in order to determine if the last IO call failed.
 818         If this returns @true, use LastError() to discover the cause of the error.
 819     */
 820     wxSocketError LastError() const;
 821
 822     /**
 823         Restore the previous state of the socket, as saved with SaveState().
 824
 825         Calls to SaveState() and RestoreState() can be nested.
 826
 827         @see SaveState()
 828     */
 829     void RestoreState();
 830
 831     /**
 832         Save the current state of the socket in a stack.
 833
 834         Socket state includes flags, as set with SetFlags(), event mask, as set
 835         with SetNotify() and Notify(), user data, as set with SetClientData().
 836         Calls to SaveState and RestoreState can be nested.
 837
 838         @see RestoreState()
 839     */
 840     void SaveState();
 841
 842     //@}
 843
 844
 845     /**
 846         @name Basic I/O
 847
 848         See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
 849     */
 850     //@{
 851
 852     /**
 853         Shut down the socket, disabling further transmission and reception of
 854         data and disable events for the socket and frees the associated system
 855         resources.
 856
 857         Upon socket destruction, Close() is automatically called, so in most cases
 858         you won't need to do it yourself, unless you explicitly want to shut down
 859         the socket, typically to notify the peer that you are closing the connection.
 860
 861         @remarks
 862         Although Close() immediately disables events for the socket, it is possible
 863         that event messages may be waiting in the application's event queue.
 864         The application must therefore be prepared to handle socket event messages even
 865         after calling Close().
 866     */
 867     virtual bool Close();
 868
 869     /**
 870         Shuts down the writing end of the socket.
 871
 872         This function simply calls the standard shutdown() function on the
 873         underlying socket, indicating that nothing will be written to this
 874         socket any more.
 875      */
 876     void ShutdownOutput();
 877
 878     /**
 879         Delete all bytes in the incoming queue.
 880
 881         This function always returns immediately and its operation is not
 882         affected by IO flags.
 883
 884         Use LastCount() to verify the number of bytes actually discarded.
 885
 886         If you use Error(), it will always return @false.
 887     */
 888     wxSocketBase& Discard();
 889
 890     /**
 891         Returns current IO flags, as set with SetFlags()
 892     */
 893     wxSocketFlags GetFlags() const;
 894
 895     /**
 896         Use this function to interrupt any wait operation currently in progress.
 897
 898         Note that this is not intended as a regular way to interrupt a Wait call,
 899         but only as an escape mechanism for exceptional situations where it is
 900         absolutely necessary to use it, for example to abort an operation due to
 901         some exception or abnormal problem. InterruptWait is automatically called
 902         when you Close() a socket (and thus also upon
 903         socket destruction), so you don't need to use it in these cases.
 904
 905         @see  Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
 906               wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
 907     */
 908     void InterruptWait();
 909
 910     /**
 911         Peek into the socket by copying the next bytes which would be read by
 912         Read() into the provided buffer.
 913
 914         Peeking a buffer doesn't delete it from the socket input queue, i.e.
 915         calling Read() will return the same data.
 916
 917         Use LastCount() to verify the number of bytes actually peeked.
 918
 919         Use Error() to determine if the operation succeeded.
 920
 921         @param buffer
 922             Buffer where to put peeked data.
 923         @param nbytes
 924             Number of bytes.
 925
 926         @return Returns a reference to the current object.
 927
 928         @remarks
 929             The exact behaviour of Peek() depends on the combination of flags being used.
 930             For a detailed explanation, see SetFlags()
 931
 932         @see Error(), LastError(), LastCount(), SetFlags()
 933     */
 934     wxSocketBase& Peek(void* buffer, wxUint32 nbytes);
 935
 936     /**
 937         Read up to the given number of bytes from the socket.
 938
 939         Use LastCount() to verify the number of bytes actually read.
 940         Use Error() to determine if the operation succeeded.
 941
 942         @param buffer
 943             Buffer where to put read data.
 944         @param nbytes
 945             Number of bytes.
 946
 947         @return Returns a reference to the current object.
 948
 949         @remarks
 950             The exact behaviour of Read() depends on the combination of flags being used.
 951             For a detailed explanation, see SetFlags()
 952
 953         @see Error(), LastError(), LastCount(),
 954              SetFlags()
 955     */
 956     wxSocketBase& Read(void* buffer, wxUint32 nbytes);
 957
 958     /**
 959         Receive a message sent by WriteMsg().
 960
 961         If the buffer passed to the function isn't big enough, the remaining
 962         bytes will be discarded. This function always waits for the buffer to
 963         be entirely filled, unless an error occurs.
 964
 965         Use LastCount() to verify the number of bytes actually read.
 966
 967         Use Error() to determine if the operation succeeded.
 968
 969         @param buffer
 970             Buffer where to put read data.
 971         @param nbytes
 972             Size of the buffer.
 973
 974         @return Returns a reference to the current object.
 975
 976         @remarks
 977             ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
 978             and it will always ignore the @b wxSOCKET_NOWAIT flag.
 979             The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
 980             For a detailed explanation, see SetFlags().
 981
 982         @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
 983     */
 984     wxSocketBase& ReadMsg(void* buffer, wxUint32 nbytes);
 985
 986     /**
 987         Use SetFlags to customize IO operation for this socket.
 988
 989         The @a flags parameter may be a combination of flags ORed together.
 990         Notice that not all combinations of flags affecting the IO calls
 991         (Read() and Write()) make sense, e.g. @b wxSOCKET_NOWAIT can't be
 992         combined with @b wxSOCKET_WAITALL nor with @b wxSOCKET_BLOCK.
 993
 994         The following flags can be used:
 995         @beginFlagTable
 996         @flag{wxSOCKET_NONE}
 997             Default mode: the socket will read some data in the IO calls and
 998             will process events to avoid blocking UI while waiting for the data
 999             to become available.
1000         @flag{wxSOCKET_NOWAIT}
1001             Don't wait for the socket to become ready in IO calls, read as much
1002             data as is available -- potentially 0 bytes -- and return
1003             immediately.
1004         @flag{wxSOCKET_WAITALL}
1005             Don't return before the entire amount of data specified in IO calls
1006             is read or written unless an error occurs. If this flag is not
1007             specified, the IO calls return as soon as any amount of data, even
1008             less than the total number of bytes, is processed.
1009         @flag{wxSOCKET_BLOCK}
1010             Don't process the UI events while waiting for the socket to become
1011             ready. This means that UI will be unresponsive during socket IO.
1012         @flag{wxSOCKET_REUSEADDR}
1013             Allows the use of an in-use port (wxServerSocket only).
1014         @flag{wxSOCKET_BROADCAST}
1015             Switches the socket to broadcast mode.
1016         @flag{wxSOCKET_NOBIND}
1017             Stops the socket from being bound to a specific adapter (normally
1018             used in conjunction with @b wxSOCKET_BROADCAST).
1019         @endFlagTable
1020
1021         For more information on socket events see @ref wxSocketFlags .
1022     */
1023     void SetFlags(wxSocketFlags flags);
1024
1025     /**
1026         Set the local address and port to use.
1027
1028         This function must always be called for the server sockets but may also
1029         be called for client sockets, if it is, @b bind() is called before @b
1030         connect().
1031     */
1032     virtual bool SetLocal(const wxIPV4address& local);
1033
1034     /**
1035         Set the default socket timeout in seconds.
1036
1037         This timeout applies to all IO calls, and also to the Wait() family of
1038         functions if you don't specify a wait interval. Initially, the default
1039         timeout is 10 minutes.
1040     */
1041     void SetTimeout(long seconds);
1042
1043     /**
1044         Put the specified data into the input queue.
1045
1046         The data in the buffer will be returned by the next call to Read().
1047
1048         This function is not affected by wxSocket flags.
1049
1050         If you use LastCount(), it will always return @a nbytes.
1051
1052         If you use Error(), it will always return @false.
1053
1054         @param buffer
1055             Buffer to be unread.
1056         @param nbytes
1057             Number of bytes.
1058
1059         @return Returns a reference to the current object.
1060
1061         @see Error(), LastCount(), LastError()
1062     */
1063     wxSocketBase& Unread(const void* buffer, wxUint32 nbytes);
1064
1065     /**
1066         Wait for any socket event.
1067
1068         Possible socket events are:
1069         @li The socket becomes readable.
1070         @li The socket becomes writable.
1071         @li An ongoing connection request has completed (wxSocketClient only)
1072         @li An incoming connection request has arrived (wxSocketServer only)
1073         @li The connection has been closed.
1074
1075         Note that it is recommended to use the individual @b WaitForXXX()
1076         functions to wait for the required condition, instead of this one.
1077
1078         @param seconds
1079             Number of seconds to wait.
1080             If -1, it will wait for the default timeout,
1081             as set with SetTimeout().
1082         @param millisecond
1083             Number of milliseconds to wait.
1084
1085         @return
1086            @true when any of the above conditions is satisfied or @false if the
1087            timeout was reached.
1088
1089         @see InterruptWait(), wxSocketServer::WaitForAccept(),
1090              WaitForLost(), WaitForRead(),
1091              WaitForWrite(), wxSocketClient::WaitOnConnect()
1092     */
1093     bool Wait(long seconds = -1, long millisecond = 0);
1094
1095     /**
1096         Wait until the connection is lost.
1097
1098         This may happen if the peer gracefully closes the connection or if the
1099         connection breaks.
1100
1101         @param seconds
1102             Number of seconds to wait.
1103             If -1, it will wait for the default timeout,
1104             as set with SetTimeout().
1105         @param millisecond
1106             Number of milliseconds to wait.
1107
1108         @return Returns @true if the connection was lost, @false if the timeout
1109                 was reached.
1110
1111         @see InterruptWait(), Wait()
1112     */
1113     bool WaitForLost(long seconds = -1, long millisecond = 0);
1114
1115     /**
1116         Wait until the socket is readable.
1117
1118         This might mean that queued data is available for reading or, for streamed
1119         sockets, that the connection has been closed, so that a read operation will
1120         complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
1121         is set, in which case the operation might still block).
1122
1123         Notice that this function should not be called if there is already data
1124         available for reading on the socket.
1125
1126         @param seconds
1127             Number of seconds to wait.
1128             If -1, it will wait for the default timeout,
1129             as set with SetTimeout().
1130         @param millisecond
1131             Number of milliseconds to wait.
1132
1133         @return Returns @true if the socket becomes readable, @false on timeout.
1134
1135         @see InterruptWait(), Wait()
1136     */
1137     bool WaitForRead(long seconds = -1, long millisecond = 0);
1138
1139     /**
1140         Wait until the socket becomes writable.
1141
1142         This might mean that the socket is ready to send new data, or for streamed
1143         sockets, that the connection has been closed, so that a write operation is
1144         guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
1145         in which case the operation might still block).
1146
1147         Notice that this function should not be called if the socket is already
1148         writable.
1149
1150         @param seconds
1151             Number of seconds to wait.
1152             If -1, it will wait for the default timeout,
1153             as set with SetTimeout().
1154         @param millisecond
1155             Number of milliseconds to wait.
1156
1157         @return Returns @true if the socket becomes writable, @false on timeout.
1158
1159         @see InterruptWait(), Wait()
1160     */
1161     bool WaitForWrite(long seconds = -1, long millisecond = 0);
1162
1163     /**
1164         Write up to the given number of bytes to the socket.
1165
1166         Use LastCount() to verify the number of bytes actually written.
1167
1168         Use Error() to determine if the operation succeeded.
1169
1170         @param buffer
1171             Buffer with the data to be sent.
1172         @param nbytes
1173             Number of bytes.
1174
1175         @return Returns a reference to the current object.
1176
1177         @remarks
1178
1179         The exact behaviour of Write() depends on the combination of flags being used.
1180         For a detailed explanation, see SetFlags().
1181
1182         @see Error(), LastError(), LastCount(), SetFlags()
1183     */
1184     wxSocketBase& Write(const void* buffer, wxUint32 nbytes);
1185
1186     /**
1187         Sends a buffer which can be read using ReadMsg().
1188
1189         WriteMsg() sends a short header before the data so that ReadMsg()
1190         knows how much data should be actually read.
1191
1192         This function always waits for the entire buffer to be sent, unless an
1193         error occurs.
1194
1195         Use LastCount() to verify the number of bytes actually written.
1196
1197         Use Error() to determine if the operation succeeded.
1198
1199         @param buffer
1200             Buffer with the data to be sent.
1201         @param nbytes
1202             Number of bytes to send.
1203
1204         @return Returns a reference to the current object.
1205
1206         @remarks
1207
1208         WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and
1209         it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of
1210         WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation,
1211         see SetFlags().
1212
1213         @see  Error(), LastError(), LastCount(), SetFlags(), ReadMsg()
1214
1215     */
1216     wxSocketBase& WriteMsg(const void* buffer, wxUint32 nbytes);
1217
1218     //@}
1219
1220
1221     /**
1222         @name Handling Socket Events
1223     */
1224     //@{
1225
1226     /**
1227         Returns a pointer of the client data for this socket, as set with
1228         SetClientData()
1229     */
1230     void* GetClientData() const;
1231
1232     /**
1233         According to the @a notify value, this function enables
1234         or disables socket events. If @a notify is @true, the events
1235         configured with SetNotify() will
1236         be sent to the application. If @a notify is @false; no events
1237         will be sent.
1238     */
1239     void Notify(bool notify);
1240
1241     /**
1242         Sets user-supplied client data for this socket. All socket events will
1243         contain a pointer to this data, which can be retrieved with
1244         the wxSocketEvent::GetClientData() function.
1245     */
1246     void SetClientData(void* data);
1247
1248     /**
1249         Sets an event handler to be called when a socket event occurs. The
1250         handler will be called for those events for which notification is
1251         enabled with SetNotify() and
1252         Notify().
1253
1254         @param handler
1255             Specifies the event handler you want to use.
1256         @param id
1257             The id of socket event.
1258
1259         @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
1260     */
1261     void SetEventHandler(wxEvtHandler& handler, int id = -1);
1262
1263     /**
1264         Specifies which socket events are to be sent to the event handler.
1265         The @a flags parameter may be combination of flags ORed together. The
1266         following flags can be used:
1267
1268         @beginFlagTable
1269         @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT.
1270         @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT.
1271         @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION.
1272         @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST.
1273         @endFlagTable
1274
1275         For example:
1276
1277         @code
1278         sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
1279         sock.Notify(true);
1280         @endcode
1281
1282         In this example, the user will be notified about incoming socket data and
1283         whenever the connection is closed.
1284
1285         For more information on socket events see @ref wxSocketEventFlags .
1286     */
1287     void SetNotify(wxSocketEventFlags flags);
1288
1289     //@}
1290 };
1291
1292
1293
1294 /**
1295     @class wxDatagramSocket
1296
1297     @todo docme
1298
1299     @library{wxnet}
1300     @category{net}
1301 */
1302 class wxDatagramSocket : public wxSocketBase
1303 {
1304 public:
1305     /**
1306         Constructor.
1307
1308         @param addr
1309             The socket address.
1310         @param flags
1311             Socket flags (See wxSocketBase::SetFlags()).
1312     */
1313     wxDatagramSocket(const wxSockAddress& addr,
1314                      wxSocketFlags flags = wxSOCKET_NONE);
1315
1316     /**
1317         Destructor. Please see wxSocketBase::Destroy().
1318     */
1319     virtual ~wxDatagramSocket();
1320
1321     /**
1322         Write a buffer of @a nbytes bytes to the socket.
1323
1324         Use wxSocketBase::LastCount() to verify the number of bytes actually wrote.
1325         Use wxSocketBase::Error() to determine if the operation succeeded.
1326
1327         @param address
1328             The address of the destination peer for this data.
1329         @param buffer
1330             Buffer where read data is.
1331         @param nbytes
1332             Number of bytes.
1333
1334         @return Returns a reference to the current object.
1335
1336         @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
1337     */
1338     wxDatagramSocket& SendTo(const wxSockAddress& address,
1339                              const void* buffer, wxUint32 nbytes);
1340 };
1341