interface/wx/socket.h

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