PageRenderTime 47ms CodeModel.GetById 2ms app.highlight 30ms RepoModel.GetById 1ms app.codeStats 1ms

/interface/wx/socket.h

https://github.com/jay/wxWidgets
C++ Header | 1470 lines | 155 code | 116 blank | 1199 comment | 0 complexity | c11a049c30e7f74f40cef1f9920c4572 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file