interface/wx/socket.h

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