/////////////////////////////////////////////////////////////////////////////
// Name: socket.h
-// Purpose: interface of wxIPV4address
+// Purpose: interface of wxIP*address, wxSocket* classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ The type of the native socket.
+
+ Notice that the definition below is simplified and this type is not always
+ int, e.g. it is a 64 bit integer type under Win64.
+
+ @since 2.9.5
+ */
+typedef int wxSOCKET_T;
+
+/**
+ @class wxIPaddress
+
+ wxIPaddress is an abstract base class for all internet protocol address
+ objects. Currently, only wxIPV4address is implemented. An experimental
+ implementation for IPV6, wxIPV6address, is being developed.
+
+ @library{wxnet}
+ @category{net}
+*/
+class wxIPaddress : public wxSockAddress
+{
+public:
+ /**
+ Internally, this is the same as setting the IP address to @b INADDR_ANY.
+
+ On IPV4 implementations, 0.0.0.0
+
+ On IPV6 implementations, ::
+
+ @return @true on success, @false if something went wrong.
+ */
+ bool AnyAddress();
+
+ /**
+ Internally, this is the same as setting the IP address to @b INADDR_BROADCAST.
+
+ On IPV4 implementations, 255.255.255.255
+
+ @return @true on success, @false if something went wrong.
+ */
+ virtual bool BroadcastAddress() = 0;
+
+ /**
+ Set the address to hostname, which can be a host name or an IP-style address
+ in a format dependent on implementation.
+
+ @return @true on success, @false if something goes wrong (invalid
+ hostname or invalid IP address).
+ */
+ bool Hostname(const wxString& hostname);
+
+ /**
+ Returns the hostname which matches the IP address.
+ */
+ wxString Hostname() const;
+
+ /**
+ Returns a wxString containing the IP address.
+ */
+ virtual wxString IPAddress() const = 0;
+
+ /**
+ Determines if current address is set to localhost.
+
+ @return @true if address is localhost, @false if internet address.
+ */
+ virtual bool IsLocalHost() const = 0;
+
+ /**
+ Set address to localhost.
+
+ On IPV4 implementations, 127.0.0.1
+
+ On IPV6 implementations, ::1
+
+ @return @true on success, @false if something went wrong.
+ */
+ bool LocalHost();
+
+ /**
+ Set the port to that corresponding to the specified service.
+
+ @return @true on success, @false if something goes wrong (invalid @a service).
+ */
+ bool Service(const wxString& service);
+
+ /**
+ Set the port to that corresponding to the specified service.
+
+ @return @true on success, @false if something goes wrong (invalid @a service).
+ */
+ bool Service(unsigned short service);
+
+ /**
+ Returns the current service.
+ */
+ unsigned short Service() const;
+};
+
+
/**
@class wxIPV4address
+ A class for working with IPv4 network addresses.
- @library{wxbase}
+ @library{wxnet}
@category{net}
*/
class wxIPV4address : public wxIPaddress
{
public:
/**
- Set address to any of the addresses of the current machine. Whenever
- possible, use this function instead of LocalHost(),
+ Set address to any of the addresses of the current machine.
+
+ Whenever possible, use this function instead of LocalHost(),
as this correctly handles multi-homed hosts and avoids other small
problems. Internally, this is the same as setting the IP address
to @b INADDR_ANY.
- @return Returns @true on success, @false if something went wrong.
+ @return @true on success, @false if something went wrong.
*/
bool AnyAddress();
- //@{
/**
- Returns the hostname which matches the IP address.
+ Set the address to hostname, which can be a host name or an IP-style address
+ in dot notation(<tt>a.b.c.d</tt>).
+
+ @return @true on success, @false if something goes wrong (invalid
+ hostname or invalid IP address).
*/
bool Hostname(const wxString& hostname);
- Return value wxString Hostname();
- //@}
+
+ /**
+ Returns the hostname which matches the IP address.
+ */
+ virtual wxString Hostname() const;
/**
Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
*/
- wxString IPAddress();
+ virtual wxString IPAddress() const;
/**
- Set address to localhost (127.0.0.1). Whenever possible, use the
- AnyAddress(),
- function instead of this one, as this will correctly handle multi-homed
- hosts and avoid other small problems.
+ Set address to localhost (127.0.0.1).
+
+ Whenever possible, use AnyAddress() instead of this one, as that one will
+ correctly handle multi-homed hosts and avoid other small problems.
+
+ @return @true on success, @false if something went wrong.
*/
bool LocalHost();
- //@{
/**
- Returns the current service.
+ Set the port to that corresponding to the specified @a service.
+
+ @return @true on success, @false if something goes wrong (invalid @a service).
*/
bool Service(const wxString& service);
- Return value bool Service(unsigned short service);
- Return value unsigned short Service();
- //@}
+
+ /**
+ Set the port to that corresponding to the specified @a service.
+
+ @return @true on success, @false if something goes wrong (invalid @a service).
+ */
+ bool Service(unsigned short service);
+
+ /**
+ Returns the current service.
+ */
+ unsigned short Service() const;
};
/**
@class wxSocketServer
+ @todo describe me.
@library{wxnet}
@category{net}
-
- @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify,
- wxSocketBase::Notify, wxSocketServer::AcceptWith
*/
class wxSocketServer : public wxSocketBase
{
public:
/**
Constructs a new server and tries to bind to the specified @e address.
- Before trying to accept new connections, test whether it succeeded with
- @ref wxSocketBase::isok wxSocketBase:IsOk.
+
+ Before trying to accept new connections, remember to test whether it succeeded
+ with wxSocketBase:IsOk().
@param address
Specifies the local address for the server (e.g. port number).
@param flags
- Socket flags (See wxSocketBase::SetFlags)
+ Socket flags (See wxSocketBase::SetFlags()).
*/
wxSocketServer(const wxSockAddress& address,
wxSocketFlags flags = wxSOCKET_NONE);
/**
Destructor (it doesn't close the accepted connections).
*/
- ~wxSocketServer();
+ virtual ~wxSocketServer();
/**
- Accepts an incoming connection request, and creates a new
- wxSocketBase object which represents
- the server-side of the connection.
+ Accepts an incoming connection request, and creates a new wxSocketBase
+ object which represents the server-side of the connection.
+
If @a wait is @true and there are no pending connections to be
accepted, it will wait for the next incoming connection to
- arrive. @b Warning: This will block the GUI.
+ arrive.
+
+ @warning This method will block the GUI.
+
If @a wait is @false, it will try to accept a pending connection
if there is one, but it will always return immediately without blocking
- the GUI. If you want to use Accept in this way, you can either check for
- incoming connections with WaitForAccept()
- or catch @b wxSOCKET_CONNECTION events, then call Accept once you know
- that there is an incoming connection waiting to be accepted.
+ the GUI. If you want to use Accept() in this way, you can either check for
+ incoming connections with WaitForAccept() or catch @b wxSOCKET_CONNECTION events,
+ then call Accept() once you know that there is an incoming connection waiting
+ to be accepted.
@return Returns an opened socket connection, or @NULL if an error
- occurred or if the wait parameter was @false and there
- were no pending connections.
+ occurred or if the wait parameter was @false and there
+ were no pending connections.
- @see WaitForAccept(), wxSocketBase::SetNotify,
- wxSocketBase::Notify, AcceptWith()
+ @see WaitForAccept(), wxSocketBase::SetNotify(),
+ wxSocketBase::Notify(), AcceptWith()
*/
wxSocketBase* Accept(bool wait = true);
@param socket
Socket to be initialized
+ @param wait
+ See Accept() for more info.
+
+ @return Returns @true on success, or @false if an error occurred or
+ if the wait parameter was @false and there were no pending
+ connections.
- @return Returns @true on success, or @false if an error occurred or if the
- wait parameter was @false and there were no pending
- connections.
+ @see WaitForAccept(), wxSocketBase::SetNotify(),
+ wxSocketBase::Notify(), Accept()
*/
bool AcceptWith(wxSocketBase& socket, bool wait = true);
/**
- This function waits for an incoming connection. Use it if you want to call
- Accept() or AcceptWith()
- with @e wait set to @false, to detect when an incoming connection is waiting
- to be accepted.
+ Wait for an incoming connection.
+
+ Use it if you want to call Accept() or AcceptWith() with @e wait set
+ to @false, to detect when an incoming connection is waiting to be accepted.
@param seconds
- Number of seconds to wait.
- If -1, it will wait for the default timeout,
- as set with SetTimeout.
+ Number of seconds to wait. If -1, it will wait for the default
+ timeout, as set with wxSocketBase::SetTimeout().
@param millisecond
Number of milliseconds to wait.
- @return Returns @true if an incoming connection arrived, @false if the
- timeout elapsed.
+ @return @true if an incoming connection arrived, @false if the timeout
+ elapsed.
+
+ @see Accept(), AcceptWith(), wxSocketBase::InterruptWait()
*/
bool WaitForAccept(long seconds = -1, long millisecond = 0);
};
-
/**
- @class wxIPaddress
+ @class wxSocketClient
- wxIPaddress is an abstract base class for all internet protocol address
- objects. Currently, only wxIPV4address
- is implemented. An experimental implementation for IPV6, wxIPV6address,
- is being developed.
+ @todo describe me.
- @library{wxbase}
+ @library{wxnet}
@category{net}
*/
-class wxIPaddress : public wxSockAddress
+class wxSocketClient : public wxSocketBase
{
public:
/**
- Internally, this is the same as setting the IP address
- to @b INADDR_ANY.
- On IPV4 implementations, 0.0.0.0
- On IPV6 implementations, ::
-
- @return Returns @true on success, @false if something went wrong.
- */
- virtual bool AnyAddress();
-
- /**
- Internally, this is the same as setting the IP address
- to @b INADDR_BROADCAST.
- On IPV4 implementations, 255.255.255.255
-
- @return Returns @true on success, @false if something went wrong.
- */
- virtual bool BroadcastAddress();
-
- //@{
- /**
- Returns the hostname which matches the IP address.
- */
- virtual bool Hostname(const wxString& hostname);
- Return value virtual wxString Hostname();
- //@}
-
- /**
- Returns a wxString containing the IP address.
- */
- virtual wxString IPAddress();
+ Constructor.
- /**
- Determines if current address is set to localhost.
+ @param flags
+ Socket flags (See wxSocketBase::SetFlags())
*/
- virtual bool IsLocalHost();
+ wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE);
/**
- Set address to localhost.
- On IPV4 implementations, 127.0.0.1
- On IPV6 implementations, ::1
-
- @return Returns @true on success, @false if something went wrong.
+ Destructor. Please see wxSocketBase::Destroy().
*/
- virtual bool LocalHost();
+ virtual ~wxSocketClient();
- //@{
/**
- Returns the current service.
- */
- virtual bool Service(const wxString& service);
- Return value virtual bool Service(unsigned short service);
- Return value virtual unsigned short Service();
- //@}
-};
-
-
+ Connects to a server using the specified address.
-/**
- @class wxSocketClient
+ If @a wait is @true, Connect() will wait until the connection
+ completes.
+ @warning This method will block the GUI.
- @library{wxnet}
- @category{net}
+ If @a wait is @false, Connect() will try to establish the connection
+ and return immediately, without blocking the GUI. When used this way,
+ even if Connect() returns @false, the connection request can be
+ completed later. To detect this, use WaitOnConnect(), or catch
+ @b wxSOCKET_CONNECTION events (for successful establishment) and
+ @b wxSOCKET_LOST events (for connection failure).
- @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify,
- wxSocketBase::Notify
-*/
-class wxSocketClient : public wxSocketBase
-{
-public:
- /**
- Constructor.
+ @param address
+ Address of the server.
+ @param wait
+ If @true, waits for the connection to complete.
- @param flags
- Socket flags (See wxSocketBase::SetFlags)
- */
- wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE);
+ @return @true if the connection is established and no error occurs.
+ If @a wait was true, and Connect() returns @false, an error
+ occurred and the connection failed.
+ If @a wait was @false, and Connect() returns @false, you should
+ still be prepared to handle the completion of this connection request,
+ either with WaitOnConnect() or by watching wxSOCKET_CONNECTION
+ and wxSOCKET_LOST events.
- /**
- Destructor. Please see wxSocketBase::Destroy.
+ @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
*/
- ~wxSocketClient();
+ virtual bool Connect(const wxSockAddress& address, bool wait = true);
- //@{
/**
Connects to a server using the specified address.
- If @a wait is @true, Connect will wait until the connection
+
+ If @a wait is @true, Connect() will wait until the connection
completes. @b Warning: This will block the GUI.
- If @a wait is @false, Connect will try to establish the connection and
- return immediately, without blocking the GUI. When used this way, even if
- Connect returns @false, the connection request can be completed later.
- To detect this, use WaitOnConnect(),
- or catch @b wxSOCKET_CONNECTION events (for successful establishment)
- and @b wxSOCKET_LOST events (for connection failure).
+
+ If @a wait is @false, Connect() will try to establish the connection
+ and return immediately, without blocking the GUI. When used this way,
+ even if Connect() returns @false, the connection request can be
+ completed later. To detect this, use WaitOnConnect(), or catch
+ @b wxSOCKET_CONNECTION events (for successful establishment) and
+ @b wxSOCKET_LOST events (for connection failure).
@param address
Address of the server.
@param local
Bind to the specified local address and port before connecting.
- The local address and port can also be set using SetLocal,
- and then using the 2-parameter Connect method.
+ The local address and port can also be set using SetLocal(),
+ and then using the 2-parameter Connect() method.
@param wait
If @true, waits for the connection to complete.
- @return Returns @true if the connection is established and no error
- occurs.
+ @return @true if the connection is established and no error occurs.
+ If @a wait was true, and Connect() returns @false, an error
+ occurred and the connection failed.
+ If @a wait was @false, and Connect() returns @false, you should
+ still be prepared to handle the completion of this connection request,
+ either with WaitOnConnect() or by watching wxSOCKET_CONNECTION
+ and wxSOCKET_LOST events.
- @see WaitOnConnect(), wxSocketBase::SetNotify,
- wxSocketBase::Notify
+ @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
*/
- bool Connect(wxSockAddress& address, bool wait = true);
- bool Connect(wxSockAddress& address, wxSockAddress& local,
+ bool Connect(const wxSockAddress& address, const wxSockAddress& local,
bool wait = true);
- //@}
/**
Wait until a connection request completes, or until the specified timeout
- elapses. Use this function after issuing a call
- to Connect() with @e wait set to @false.
+ elapses. Use this function after issuing a call to Connect() with
+ @e wait set to @false.
@param seconds
Number of seconds to wait.
- If -1, it will wait for the default timeout,
- as set with SetTimeout.
- @param millisecond
+ If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout().
+ @param milliseconds
Number of milliseconds to wait.
- @return WaitOnConnect returns @true if the connection request completes.
- This does not necessarily mean that the connection was
- successfully established; it might also happen that the
- connection was refused by the peer. Use IsConnected to
- distinguish between these two situations.
+ @return
+ WaitOnConnect() returns @true if the connection request completes.
+ This does not necessarily mean that the connection was
+ successfully established; it might also happen that the
+ connection was refused by the peer. Use wxSocketBase::IsConnected()
+ to distinguish between these two situations.
+ @n @n If the timeout elapses, WaitOnConnect() returns @false.
+ @n @n These semantics allow code like this:
+ @code
+ // Issue the connection request
+ client->Connect(addr, false);
+
+ // Wait until the request completes or until we decide to give up
+ bool waitmore = true;
+ while ( !client->WaitOnConnect(seconds, millis) && waitmore )
+ {
+ // possibly give some feedback to the user,
+ // and update waitmore as needed.
+ }
+ bool success = client->IsConnected();
+ @endcode
*/
bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
};
You are unlikely to need to use this class: only wxSocketBase uses it.
- @library{wxbase}
- @category{FIXME}
+ @library{wxnet}
+ @category{net}
@see wxSocketBase, wxIPaddress, wxIPV4address
*/
/**
Default destructor.
*/
- ~wxSockAddress();
+ virtual ~wxSockAddress();
/**
Delete all informations about the address.
*/
- void Clear();
+ virtual void Clear();
/**
Returns the length of the socket address.
*/
int SockAddrLen();
+
+ /**
+ Returns the pointer to the low-level representation of the address.
+
+ This can be used to pass socket address information to a 3rd party
+ library.
+
+ @return
+ Pointer to a sockaddr-derived struct.
+ */
+ const sockaddr *GetAddressData() const;
+
+ /**
+ Returns the length of the buffer retrieved by GetAddressData().
+
+ @return
+ The size of the sockaddr-derived struct corresponding to this
+ address.
+ */
+ int GetAddressDataLen() const;
};
@class wxSocketEvent
This event class contains information about socket events.
+ This kind of events are sent to the event handler specified with
+ wxSocketBase::SetEventHandler.
+
+ @beginEventTable{wxSocketEvent}
+ @event{EVT_SOCKET(id, func)}
+ Process a socket event, supplying the member function.
+ @endEventTable
@library{wxnet}
@category{net}
/**
Gets the client data of the socket which generated this event, as
- set with wxSocketBase::SetClientData.
+ set with wxSocketBase::SetClientData().
*/
- void* GetClientData();
+ void* GetClientData() const;
/**
- Returns the socket object to which this event refers to. This makes
- it possible to use the same event handler for different sockets.
+ Returns the socket object to which this event refers to.
+ This makes it possible to use the same event handler for different sockets.
*/
wxSocketBase* GetSocket() const;
};
+/**
+ wxSocket error return values.
+*/
+enum wxSocketError
+{
+ wxSOCKET_NOERROR, ///< No error happened.
+ wxSOCKET_INVOP, ///< Invalid operation.
+ wxSOCKET_IOERR, ///< Input/Output error.
+ wxSOCKET_INVADDR, ///< Invalid address passed to wxSocket.
+ wxSOCKET_INVSOCK, ///< Invalid socket (uninitialized).
+ wxSOCKET_NOHOST, ///< No corresponding host.
+ wxSOCKET_INVPORT, ///< Invalid port.
+ wxSOCKET_WOULDBLOCK, ///< The socket is non-blocking and the operation would block.
+ wxSOCKET_TIMEDOUT, ///< The timeout for this operation expired.
+ wxSOCKET_MEMERR ///< Memory exhausted.
+};
+
+
+/**
+ @anchor wxSocketEventFlags
+
+ wxSocket Event Flags.
+
+ A brief note on how to use these events:
+
+ The @b wxSOCKET_INPUT event will be issued whenever there is data available
+ for reading. This will be the case if the input queue was empty and new data
+ arrives, or if the application has read some data yet there is still more data
+ available. This means that the application does not need to read all available
+ data in response to a @b wxSOCKET_INPUT event, as more events will be produced
+ as necessary.
+
+ The @b wxSOCKET_OUTPUT event is issued when a socket is first connected with
+ Connect() or accepted with Accept(). After that, new events will be generated
+ only after an output operation fails with @b wxSOCKET_WOULDBLOCK and buffer space
+ becomes available again. This means that the application should assume that it can
+ write data to the socket until an @b wxSOCKET_WOULDBLOCK error occurs; after this,
+ whenever the socket becomes writable again the application will be notified with
+ another @b wxSOCKET_OUTPUT event.
+
+ The @b wxSOCKET_CONNECTION event is issued when a delayed connection request completes
+ successfully (client) or when a new connection arrives at the incoming queue (server).
+
+ The @b wxSOCKET_LOST event is issued when a close indication is received for the socket.
+ This means that the connection broke down or that it was closed by the peer. Also, this
+ event will be issued if a connection request fails.
+*/
+enum wxSocketEventFlags
+{
+ wxSOCKET_INPUT, ///< There is data available for reading.
+ wxSOCKET_OUTPUT, ///< The socket is ready to be written to.
+ wxSOCKET_CONNECTION, ///< Incoming connection request (server), or
+ ///< successful connection establishment (client).
+ wxSOCKET_LOST ///< The connection has been closed.
+};
+
+
+/**
+ @anchor wxSocketFlags
+
+ wxSocket Flags.
+
+ A brief overview on how to use these flags follows.
+
+ If no flag is specified (this is the same as @b wxSOCKET_NONE),
+ IO calls will return after some data has been read or written, even
+ when the transfer might not be complete. This is the same as issuing
+ exactly one blocking low-level call to @b recv() or @b send(). Note
+ that @e blocking here refers to when the function returns, not
+ to whether the GUI blocks during this time.
+
+ If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
+ Read operations will retrieve only available data. Write operations will
+ write as much data as possible, depending on how much space is available
+ in the output buffer. This is the same as issuing exactly one nonblocking
+ low-level call to @b recv() or @b send(). Note that @e nonblocking here
+ refers to when the function returns, not to whether the GUI blocks during
+ this time. Also note that this flag impacts both Read and Write
+ operations. If it is desired to control Read independently of Write, for
+ example you want no wait on Read(), but you do want to wait on Write(), then
+ use wxSOCKET_NOWAIT_READ and wxSOCKET_NOWAIT_WRITE.
+
+ If @b wxSOCKET_NOWAIT_READ (this flag is new since wxWidgets 2.9.5) is
+ specified, Read operations will return immediately. Read operations will
+ retrieve only available data. This is the same as issuing exactly one
+ nonblocking low-level call to @b recv(). Note that @e nonblocking here
+ refers to when the function returns, not to whether the GUI blocks during
+ this time. This flag should not be enabled if ReadMsg() is going to be
+ used (it will be ignored), if you do then thread-safety may be at risk.
+ Note that wxSOCKET_NOWAIT_READ impacts only Read operations and does not
+ impact Write operations, allowing Read and Write operations to be set
+ differently.
+
+ If @b wxSOCKET_NOWAIT_WRITE (this flag is new since wxWidgets 2.9.5) is
+ specified, Write operations will return immediately. Write operations will
+ write as much data as possible, depending on how much space is available in
+ the output buffer. This is the same as issuing exactly one nonblocking
+ low-level call to @b send(). Note that @e nonblocking here refers to when
+ the function returns, not to whether the GUI blocks during this time. This
+ flag should not be enabled if WriteMsg() is going to be used (it will be
+ ignored), if you use it then thread safety may be at risk. Note that
+ wxSOCKET_NOWAIT_WRITE impacts only Write operations and does not impact
+ Write operations, allowing Read and Write operations to be set differently.
+
+ If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
+ the data has been read or written (or until an error occurs), blocking if
+ necessary, and issuing several low level calls if necessary. This is the
+ same as having a loop which makes as many blocking low-level calls to
+ @b recv() or @b send() as needed so as to transfer all the data. Note
+ that @e blocking here refers to when the function returns, not
+ to whether the GUI blocks during this time. Note that wxSOCKET_WAITALL
+ impacts both Read and Write operations. If you desire to wait
+ for all on just Read operations, but not on Write operations, (or vice versa),
+ use wxSOCKET_WAITALL_READ or wxSOCKET_WAITALL_WRITE.
+
+ If @b wxSOCKET_WAITALL_READ (this flag is new since wxWidgets 2.9.5) is
+ specified, Read operations won't return until ALL the data has been read
+ (or until an error occurs), blocking if necessary, and issuing several low
+ level calls if necessary. This is the same as having a loop which makes as
+ many blocking low-level calls to @b recv() as needed so as to transfer all
+ the data. Note that @e blocking here refers to when the function returns,
+ not to whether the GUI blocks during this time. Note that
+ wxSOCKET_WAITALL_READ only has an impact on Read operations, and has no
+ impact on Write operations, allowing Read and Write operations to have
+ different settings.
+
+ If @b wxSOCKET_WAITALL_WRITE (this flag is new since wxWidgets 2.9.5) is
+ specified, Write() and WriteMsg() calls won't return until ALL the data has
+ been written (or until an error occurs), blocking if necessary, and issuing
+ several low level calls if necessary. This is the same as having a loop
+ which makes as many blocking low-level calls to @b send() as needed so as
+ to transfer all the data. Note that @e blocking here refers to when the
+ function returns, not to whether the GUI blocks during this time. Note
+ that wxSOCKET_WAITALL_WRITE only has an impact on Write operations, and has
+ no impact on Read operations, allowing Read and Write operations to have
+ different settings.
+
+ The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
+ IO operations. If this flag is specified, the socket will not yield
+ during IO calls, so the GUI will remain blocked until the operation
+ completes. If it is not used, then the application must take extra
+ care to avoid unwanted reentrance.
+
+ The @b wxSOCKET_REUSEADDR flag controls the use of the @b SO_REUSEADDR standard
+ @b setsockopt() flag. This flag allows the socket to bind to a port that is
+ already in use. This is mostly used on UNIX-based systems to allow rapid starting
+ and stopping of a server, otherwise you may have to wait several minutes for the
+ port to become available.
+
+ @b wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
+ particular local port for an outgoing connection.
+ This option can have surprising platform dependent behaviour, so check the
+ documentation for your platform's implementation of setsockopt().
+
+ Note that on BSD-based systems(e.g. Mac OS X), use of
+ @b wxSOCKET_REUSEADDR implies @b SO_REUSEPORT in addition to
+ @b SO_REUSEADDR to be consistent with Windows.
+
+ The @b wxSOCKET_BROADCAST flag controls the use of the @b SO_BROADCAST standard
+ @b setsockopt() flag. This flag allows the socket to use the broadcast address,
+ and is generally used in conjunction with @b wxSOCKET_NOBIND and
+ wxIPaddress::BroadcastAddress().
+
+ So:
+ - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
+ - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
+ read or write ANY data.
+ - @b wxSOCKET_WAITALL will only return when it has read or written ALL
+ the data.
+ - @b wxSOCKET_BLOCK has nothing to do with the previous flags and
+ it controls whether the GUI blocks.
+ - @b wxSOCKET_REUSEADDR controls special platform-specific behaviour for
+ reusing local addresses/ports.
+*/
+enum
+{
+ wxSOCKET_NONE = 0, ///< Normal functionality.
+ wxSOCKET_NOWAIT = 1, ///< Read/write as much data as possible and return immediately.
+ wxSOCKET_WAITALL = 2, ///< Wait for all required data to be read/written unless an error occurs.
+ wxSOCKET_BLOCK = 4, ///< Block the GUI (do not yield) while reading/writing data.
+ wxSOCKET_REUSEADDR = 8, ///< Allows the use of an in-use port.
+ wxSOCKET_BROADCAST = 16, ///< Switches the socket to broadcast mode
+ wxSOCKET_NOBIND = 32, ///< Stops the socket from being bound to a specific
+ ///< adapter (normally used in conjunction with
+ ///< @b wxSOCKET_BROADCAST)
+ wxSOCKET_NOWAIT_READ = 64, ///< Read as much data as possible and return immediately
+ wxSOCKET_WAITALL_READ = 128, ///< Wait for all required data to be read unless an error occurs.
+ wxSOCKET_NOWAIT_WRITE = 256, ///< Write as much data as possible and return immediately
+ wxSOCKET_WAITALL_WRITE = 512 ///< Wait for all required data to be written unless an error occurs.
+};
+
/**
@class wxSocketBase
wxSocketBase is the base class for all socket-related objects, and it
defines all basic IO functionality.
- Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x)
- If you want to use sockets or derived classes such as wxFTP in a secondary
- thread,
- call wxSocketBase::Initialize() (undocumented) from the main thread before
- creating
- any sockets - in wxApp::OnInit for example.
- See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
- http://www.litwindow.com/knowhow/knowhow.html for more details.
+ @note
+ When using wxSocket from multiple threads, even implicitly (e.g. by using
+ wxFTP or wxHTTP in another thread) you must initialize the sockets from the
+ main thread by calling Initialize() before creating the other ones.
+
+ @beginEventEmissionTable{wxSocketEvent}
+ @event{EVT_SOCKET(id, func)}
+ Process a @c wxEVT_SOCKET event.
+ See @ref wxSocketEventFlags and @ref wxSocketFlags for more info.
+ @endEventTable
@library{wxnet}
@category{net}
- @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets
- "Sockets sample"
+ @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
+ @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
*/
class wxSocketBase : public wxObject
{
public:
- /**
- Default constructor. Don't use it directly; instead, use
- wxSocketClient to construct a socket client, or
- wxSocketServer to construct a socket server.
- */
- wxSocketBase();
/**
- Destructor. Do not destroy a socket using the delete operator directly;
- use Destroy() instead. Also, do not create
- socket objects in the stack.
+ @name Construction and Destruction
*/
- ~wxSocketBase();
+ //@{
/**
- Functions that perform basic IO functionality.
- Close()
+ Default constructor.
- Discard()
+ Don't use it directly; instead, use wxSocketClient to construct a socket client,
+ or wxSocketServer to construct a socket server.
+ */
+ wxSocketBase();
- Peek()
+ /**
+ Destructor.
- Read()
+ Do not destroy a socket using the delete operator directly;
+ use Destroy() instead. Also, do not create socket objects in the stack.
+ */
+ virtual ~wxSocketBase();
- ReadMsg()
+ /**
+ Destroys the socket safely.
- Unread()
+ Use this function instead of the delete operator, since otherwise socket events
+ could reach the application even after the socket has been destroyed. To prevent
+ this problem, this function appends the wxSocket to a list of object to be deleted
+ on idle time, after all events have been processed. For the same reason, you should
+ avoid creating socket objects in the stack.
- Write()
+ Destroy() calls Close() automatically.
- WriteMsg()
- Functions that perform a timed wait on a certain IO condition.
- InterruptWait()
+ @return Always @true.
+ */
+ bool Destroy();
- Wait()
+ /**
+ Perform the initialization needed in order to use the sockets.
- WaitForLost()
+ This function is called from wxSocket constructor implicitly and so
+ normally doesn't need to be called explicitly. There is however one
+ important exception: as this function must be called from the main
+ (UI) thread, if you use wxSocket from multiple threads you must call
+ Initialize() from the main thread before creating wxSocket objects in
+ the other ones.
- WaitForRead()
+ It is safe to call this function multiple times (only the first call
+ does anything) but you must call Shutdown() exactly once for every call
+ to Initialize().
- WaitForWrite()
+ This function should only be called from the main thread.
- and also:
- wxSocketServer::WaitForAccept
+ @return
+ @true if the sockets can be used, @false if the initialization
+ failed and sockets are not available at all.
+ */
+ static bool Initialize();
- wxSocketClient::WaitOnConnect
- Functions that allow applications to customize socket IO as needed.
- GetFlags()
+ /**
+ Shut down the sockets.
- SetFlags()
+ This function undoes the call to Initialize() and must be called after
+ every successful call to Initialize().
- SetTimeout()
+ This function should only be called from the main thread, just as
+ Initialize().
+ */
+ static void Shutdown();
- SetLocal()
- */
+ //@}
/**
- This function shuts down the socket, disabling further transmission and
- reception of data; it also disables events for the socket and frees the
- associated system resources. Upon socket destruction, Close is automatically
- called, so in most cases you won't need to do it yourself, unless you
- explicitly want to shut down the socket, typically to notify the peer
- that you are closing the connection.
+ @name Socket State
*/
- void Close();
+ //@{
/**
- @ref construct() wxSocketBase
-
- @ref destruct() ~wxSocketBase
+ Returns @true if an error occurred in the last IO operation.
- Destroy()
+ Use this function to check for an error condition after one of the
+ following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg().
*/
-
+ bool Error() const;
/**
- Destroys the socket safely. Use this function instead of the delete operator,
- since otherwise socket events could reach the application even after the
- socket has been destroyed. To prevent this problem, this function appends
- the wxSocket to a list of object to be deleted on idle time, after all
- events have been processed. For the same reason, you should avoid creating
- socket objects in the stack.
- Destroy calls Close() automatically.
+ Return the local address of the socket.
- @return Always @true.
+ @return @true if no error happened, @false otherwise.
*/
- bool Destroy();
+ virtual bool GetLocal(wxSockAddress& addr) const;
/**
- This function simply deletes all bytes in the incoming queue. This function
- always returns immediately and its operation is not affected by IO flags.
- Use LastCount() to verify the number of bytes actually discarded.
- If you use Error(), it will always return @false.
+ Return the peer address field of the socket.
+
+ @return @true if no error happened, @false otherwise.
*/
- wxSocketBase Discard();
+ virtual bool GetPeer(wxSockAddress& addr) const;
/**
- Returns @true if an error occurred in the last IO operation.
- Use this function to check for an error condition after one of the
- following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
- */
- bool Error() const;
+ Return the socket timeout in seconds.
+
+ The timeout can be set using SetTimeout() and is 10 minutes by default.
+ */
+ long GetTimeout() const;
/**
- Returns a pointer of the client data for this socket, as set with
- SetClientData()
+ Returns @true if the socket is connected.
*/
- void* GetClientData() const;
+ bool IsConnected() const;
/**
- Returns current IO flags, as set with SetFlags()
+ Check if the socket can be currently read or written.
+
+ This might mean that queued data is available for reading or, for streamed
+ sockets, that the connection has been closed, so that a read operation will
+ complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
+ is set, in which case the operation might still block).
*/
- wxSocketFlags GetFlags() const;
+ bool IsData();
/**
- This function returns the local address field of the socket. The local
- address field contains the complete local address of the socket (local
- address, local port, ...).
-
- @return @true if no error happened, @false otherwise.
+ Returns @true if the socket is not connected.
*/
- bool GetLocal(wxSockAddress& addr) const;
+ bool IsDisconnected() const;
/**
- This function returns the peer address field of the socket. The peer
- address field contains the complete peer host address of the socket
- (address, port, ...).
+ Returns @true if the socket is initialized and ready and @false in other
+ cases.
- @return @true if no error happened, @false otherwise.
+ @remarks
+ For wxSocketClient, IsOk() won't return @true unless the client is connected to a server.
+ For wxSocketServer, IsOk() will return @true if the server could bind to the specified address
+ and is already listening for new connections.
+ IsOk() does not check for IO errors; use Error() instead for that purpose.
*/
- bool GetPeer(wxSockAddress& addr) const;
+ bool IsOk() const;
/**
- Functions that allow applications to receive socket events.
- Notify()
+ Returns the number of bytes read or written by the last IO call.
- SetNotify()
+ Use this function to get the number of bytes actually transferred
+ after using one of the following IO calls: Discard(), Peek(), Read(),
+ ReadMsg(), Unread(), Write(), WriteMsg().
- GetClientData()
+ @deprecated
+ This function is kept mostly for backwards compatibility. Use
+ LastReadCount() or LastWriteCount() instead. LastCount() is still
+ needed for use with less commonly used functions: Discard(),
+ Peek(), and Unread().
+ */
+ wxUint32 LastCount() const;
- SetClientData()
+ /**
+ Returns the number of bytes read by the last Read() or ReadMsg()
+ call (receive direction only).
+
+ This function is thread-safe, in case Read() is executed in a
+ different thread than Write(). Use LastReadCount() instead of
+ LastCount() for this reason.
+
+ Unlike LastCount(), the functions Discard(), Peek(), and Unread()
+ are currently not supported by LastReadCount().
- SetEventHandler()
+ @since 2.9.5
*/
+ wxUint32 LastReadCount() const;
+
+ /**
+ Returns the number of bytes written by the last Write() or WriteMsg()
+ call (transmit direction only).
+ This function is thread-safe, in case Write() is executed in a
+ different thread than Read(). Use LastWriteCount() instead of
+ LastCount() for this reason.
+
+ @since 2.9.5
+ */
+ wxUint32 LastWriteCount() const;
/**
- Use this function to interrupt any wait operation currently in progress.
- Note that this is not intended as a regular way to interrupt a Wait call,
- but only as an escape mechanism for exceptional situations where it is
- absolutely necessary to use it, for example to abort an operation due to
- some exception or abnormal problem. InterruptWait is automatically called
- when you Close() a socket (and thus also upon
- socket destruction), so you don't need to use it in these cases.
- Wait(),
- wxSocketServer::WaitForAccept,
- WaitForLost(),
- WaitForRead(),
- WaitForWrite(),
- wxSocketClient::WaitOnConnect
+ Returns the last wxSocket error. See @ref wxSocketError .
+
+ @note
+ This function merely returns the last error code,
+ but it should not be used to determine if an error has occurred (this
+ is because successful operations do not change the LastError value).
+ Use Error() first, in order to determine if the last IO call failed.
+ If this returns @true, use LastError() to discover the cause of the error.
*/
- void InterruptWait();
+ wxSocketError LastError() const;
/**
- Returns @true if the socket is connected.
+ Restore the previous state of the socket, as saved with SaveState().
+
+ Calls to SaveState() and RestoreState() can be nested.
+
+ @see SaveState()
*/
- bool IsConnected() const;
+ void RestoreState();
/**
- This function waits until the socket is readable. This might mean that
- queued data is available for reading or, for streamed sockets, that
- the connection has been closed, so that a read operation will complete
- immediately without blocking (unless the @b wxSOCKET_WAITALL flag
- is set, in which case the operation might still block).
+ Save the current state of the socket in a stack.
+
+ Socket state includes flags, as set with SetFlags(), event mask, as set
+ with SetNotify() and Notify(), user data, as set with SetClientData().
+ Calls to SaveState and RestoreState can be nested.
+
+ @see RestoreState()
*/
- bool IsData() const;
+ void SaveState();
+
+ //@}
+
/**
- Returns @true if the socket is not connected.
+ @name Basic I/O
+
+ See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
*/
- bool IsDisconnected() const;
+ //@{
/**
- Returns @true if the socket is initialized and ready and @false in other
- cases.
+ Shut down the socket, disabling further transmission and reception of
+ data and disable events for the socket and frees the associated system
+ resources.
+
+ Upon socket destruction, Close() is automatically called, so in most cases
+ you won't need to do it yourself, unless you explicitly want to shut down
+ the socket, typically to notify the peer that you are closing the connection.
+
+ @remarks
+ Although Close() immediately disables events for the socket, it is possible
+ that event messages may be waiting in the application's event queue.
+ The application must therefore be prepared to handle socket event messages even
+ after calling Close().
*/
- bool IsOk() const;
+ virtual bool Close();
/**
- Returns the number of bytes read or written by the last IO call.
- Use this function to get the number of bytes actually transferred
- after using one of the following IO calls: Discard, Peek, Read,
- ReadMsg, Unread, Write, WriteMsg.
+ Shuts down the writing end of the socket.
+
+ This function simply calls the standard shutdown() function on the
+ underlying socket, indicating that nothing will be written to this
+ socket any more.
+ */
+ void ShutdownOutput();
+
+ /**
+ Delete all bytes in the incoming queue.
+
+ This function always returns immediately and its operation is not
+ affected by IO flags.
+
+ Use LastCount() to verify the number of bytes actually discarded.
+
+ If you use Error(), it will always return @false.
*/
- wxUint32 LastCount() const;
+ wxSocketBase& Discard();
/**
- Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket
- errors".
- Please note that this function merely returns the last error code,
- but it should not be used to determine if an error has occurred (this
- is because successful operations do not change the LastError value).
- Use Error() first, in order to determine
- if the last IO call failed. If this returns @true, use LastError
- to discover the cause of the error.
+ Returns current IO flags, as set with SetFlags()
*/
- wxSocketError LastError() const;
+ wxSocketFlags GetFlags() const;
/**
- According to the @a notify value, this function enables
- or disables socket events. If @a notify is @true, the events
- configured with SetNotify() will
- be sent to the application. If @a notify is @false; no events
- will be sent.
+ Use this function to interrupt any wait operation currently in progress.
+
+ Note that this is not intended as a regular way to interrupt a Wait call,
+ but only as an escape mechanism for exceptional situations where it is
+ absolutely necessary to use it, for example to abort an operation due to
+ some exception or abnormal problem. InterruptWait is automatically called
+ when you Close() a socket (and thus also upon
+ socket destruction), so you don't need to use it in these cases.
+
+ @see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
+ wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
*/
- void Notify(bool notify);
+ void InterruptWait();
/**
- This function peeks a buffer of @a nbytes bytes from the socket.
- Peeking a buffer doesn't delete it from the socket input queue.
+ Peek into the socket by copying the next bytes which would be read by
+ Read() into the provided buffer.
+
+ Peeking a buffer doesn't delete it from the socket input queue, i.e.
+ calling Read() will return the same data.
+
Use LastCount() to verify the number of bytes actually peeked.
+
Use Error() to determine if the operation succeeded.
@param buffer
@return Returns a reference to the current object.
- @see Error(), LastError(), LastCount(),
- SetFlags()
+ @remarks
+ The exact behaviour of Peek() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags()
+
+ @see Error(), LastError(), LastCount(), SetFlags()
*/
- wxSocketBase Peek(void* buffer, wxUint32 nbytes);
+ wxSocketBase& Peek(void* buffer, wxUint32 nbytes);
/**
- This function reads a buffer of @a nbytes bytes from the socket.
- Use LastCount() to verify the number of bytes actually read.
+ Read up to the given number of bytes from the socket.
+
+ Use LastReadCount() to verify the number of bytes actually read.
Use Error() to determine if the operation succeeded.
@param buffer
@return Returns a reference to the current object.
- @see Error(), LastError(), LastCount(),
+ @remarks
+ The exact behaviour of Read() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags()
+
+ @see Error(), LastError(), LastReadCount(),
SetFlags()
*/
- wxSocketBase Read(void* buffer, wxUint32 nbytes);
+ wxSocketBase& Read(void* buffer, wxUint32 nbytes);
/**
- This function reads a buffer sent by WriteMsg()
- on a socket. If the buffer passed to the function isn't big enough, the
- remaining bytes will be discarded. This function always waits for the
- buffer to be entirely filled, unless an error occurs.
- Use LastCount() to verify the number of bytes actually read.
+ Receive a message sent by WriteMsg().
+
+ If the buffer passed to the function isn't big enough, the remaining
+ bytes will be discarded. This function always waits for the buffer to
+ be entirely filled, unless an error occurs.
+
+ Use LastReadCount() to verify the number of bytes actually read.
+
Use Error() to determine if the operation succeeded.
@param buffer
@return Returns a reference to the current object.
- @see Error(), LastError(), LastCount(),
- SetFlags(), WriteMsg()
- */
- wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes);
-
- /**
- This function restores the previous state of the socket, as saved
- with SaveState()
- Calls to SaveState and RestoreState can be nested.
-
- @see SaveState()
- */
- void RestoreState();
-
- /**
- This function saves the current state of the socket in a stack. Socket
- state includes flags, as set with SetFlags(),
- event mask, as set with SetNotify() and
- Notify(), user data, as set with
- SetClientData().
- Calls to SaveState and RestoreState can be nested.
-
- @see RestoreState()
- */
- void SaveState();
-
- /**
- Sets user-supplied client data for this socket. All socket events will
- contain a pointer to this data, which can be retrieved with
- the wxSocketEvent::GetClientData function.
- */
- void SetClientData(void* data);
-
- /**
- Sets an event handler to be called when a socket event occurs. The
- handler will be called for those events for which notification is
- enabled with SetNotify() and
- Notify().
-
- @param handler
- Specifies the event handler you want to use.
- @param id
- The id of socket event.
+ @remarks
+ ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
+ and it will always ignore the @b wxSOCKET_NOWAIT flag.
+ The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
+ For a detailed explanation, see SetFlags().
+ For thread safety, in case ReadMsg() and WriteMsg() are called in
+ different threads, it is a good idea to call
+ SetFlags(wxSOCKET_WAITALL|wx_SOCKET_BLOCK) before the first calls
+ to ReadMsg() and WriteMsg() in different threads, as each of these
+ functions will call SetFlags() which performs read/modify/write. By
+ setting these flags before the multi-threading, it will ensure that
+ they don't get reset by thread race conditions.
- @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
+ @see Error(), LastError(), LastReadCount(), SetFlags(), WriteMsg()
*/
- void SetEventHandler(wxEvtHandler& handler, int id = -1);
+ wxSocketBase& ReadMsg(void* buffer, wxUint32 nbytes);
/**
Use SetFlags to customize IO operation for this socket.
+
The @a flags parameter may be a combination of flags ORed together.
- The following flags can be used:
+ Notice that not all combinations of flags affecting the IO calls
+ (Read() and Write()) make sense, e.g. @b wxSOCKET_NOWAIT can't be
+ combined with @b wxSOCKET_WAITALL nor with @b wxSOCKET_BLOCK.
- @b wxSOCKET_NONE
-
- Normal functionality.
-
- @b wxSOCKET_NOWAIT
-
- Read/write as much data as possible and return immediately.
-
- @b wxSOCKET_WAITALL
-
- Wait for all required data to be read/written unless an error occurs.
-
- @b wxSOCKET_BLOCK
-
- Block the GUI (do not yield) while reading/writing data.
-
- @b wxSOCKET_REUSEADDR
-
- Allows the use of an in-use port (wxServerSocket only)
-
- @b wxSOCKET_BROADCAST
-
- Switches the socket to broadcast mode
-
- @b wxSOCKET_NOBIND
-
- Stops the socket from being bound to a specific adapter (normally used in
- conjunction with @b wxSOCKET_BROADCAST)
-
- A brief overview on how to use these flags follows.
- If no flag is specified (this is the same as @b wxSOCKET_NONE),
- IO calls will return after some data has been read or written, even
- when the transfer might not be complete. This is the same as issuing
- exactly one blocking low-level call to recv() or send(). Note
- that @e blocking here refers to when the function returns, not
- to whether the GUI blocks during this time.
- If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
- Read operations will retrieve only available data. Write operations will
- write as much data as possible, depending on how much space is available
- in the output buffer. This is the same as issuing exactly one nonblocking
- low-level call to recv() or send(). Note that @e nonblocking here
- refers to when the function returns, not to whether the GUI blocks during
- this time.
- If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
- the data has been read or written (or until an error occurs), blocking if
- necessary, and issuing several low level calls if necessary. This is the
- same as having a loop which makes as many blocking low-level calls to
- recv() or send() as needed so as to transfer all the data. Note
- that @e blocking here refers to when the function returns, not
- to whether the GUI blocks during this time.
- The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
- IO operations. If this flag is specified, the socket will not yield
- during IO calls, so the GUI will remain blocked until the operation
- completes. If it is not used, then the application must take extra
- care to avoid unwanted reentrance.
- The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard
- setsockopt() flag. This flag allows the socket to bind to a port that is
- already in use.
- This is mostly used on UNIX-based systems to allow rapid starting and stopping
- of a server -
- otherwise you may have to wait several minutes for the port to become available.
- wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
- particular local port
- for an outgoing connection.
- This option can have surprising platform dependent behavior, so check the
- documentation for
- your platform's implementation of setsockopt(). Note that on BSD-based systems
- (e.g. Mac OS X),
- use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to
- be consistent
- with Windows.
- The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard
- setsockopt() flag. This flag allows the socket to use the broadcast address,
- and is generally
- used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress.
- So:
- @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
- @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
- read or write ANY data.
- @b wxSOCKET_WAITALL will only return when it has read or written ALL
- the data.
- @b wxSOCKET_BLOCK has nothing to do with the previous flags and
- it controls whether the GUI blocks.
- @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
- reusing local addresses/ports.
+ The following flags can be used:
+ @beginFlagTable
+ @flag{wxSOCKET_NONE}
+ Default mode: the socket will read some data in the IO calls and
+ will process events to avoid blocking UI while waiting for the data
+ to become available.
+ @flag{wxSOCKET_NOWAIT}
+ Don't wait for the socket to become ready in IO calls, read as much
+ data as is available -- potentially 0 bytes -- and return
+ immediately.
+ @flag{wxSOCKET_WAITALL}
+ Don't return before the entire amount of data specified in IO calls
+ is read or written unless an error occurs. If this flag is not
+ specified, the IO calls return as soon as any amount of data, even
+ less than the total number of bytes, is processed.
+ @flag{wxSOCKET_BLOCK}
+ Don't process the UI events while waiting for the socket to become
+ ready. This means that UI will be unresponsive during socket IO.
+ @flag{wxSOCKET_REUSEADDR}
+ Allows the use of an in-use port (wxServerSocket only).
+ @flag{wxSOCKET_BROADCAST}
+ Switches the socket to broadcast mode.
+ @flag{wxSOCKET_NOBIND}
+ Stops the socket from being bound to a specific adapter (normally
+ used in conjunction with @b wxSOCKET_BROADCAST).
+ @endFlagTable
+
+ For more information on socket events see @ref wxSocketFlags .
*/
void SetFlags(wxSocketFlags flags);
/**
- This function allows you to set the local address and port,
- useful when an application needs to reuse a particular port. When
- a local port is set for a wxSocketClient,
- @b bind will be called before @b connect.
- */
- bool SetLocal(wxIPV4address& local);
-
- /**
- SetNotify specifies which socket events are to be sent to the event handler.
- The @a flags parameter may be combination of flags ORed together. The
- following flags can be used:
-
- @b wxSOCKET_INPUT_FLAG
-
- to receive wxSOCKET_INPUT
-
- @b wxSOCKET_OUTPUT_FLAG
-
- to receive wxSOCKET_OUTPUT
-
- @b wxSOCKET_CONNECTION_FLAG
-
- to receive wxSOCKET_CONNECTION
+ Set the local address and port to use.
- @b wxSOCKET_LOST_FLAG
-
- to receive wxSOCKET_LOST
-
- For example:
-
- In this example, the user will be notified about incoming socket data and
- whenever the connection is closed.
- For more information on socket events see @ref overview_wxsocketbase "wxSocket
- events".
+ This function must always be called for the server sockets but may also
+ be called for client sockets, if it is, @b bind() is called before @b
+ connect().
*/
- void SetNotify(wxSocketEventFlags flags);
+ virtual bool SetLocal(const wxIPV4address& local);
/**
- This function sets the default socket timeout in seconds. This timeout
- applies to all IO calls, and also to the Wait() family
- of functions if you don't specify a wait interval. Initially, the default
+ Set the default socket timeout in seconds.
+
+ This timeout applies to all IO calls, and also to the Wait() family of
+ functions if you don't specify a wait interval. Initially, the default
timeout is 10 minutes.
*/
- void SetTimeout(int seconds);
+ void SetTimeout(long seconds);
/**
- Functions to retrieve current state and miscellaneous info.
- Error()
-
- GetLocal()
+ Put the specified data into the input queue.
- GetPeer()
- IsConnected()
+ The data in the buffer will be returned by the next call to Read().
- IsData()
+ This function is not affected by wxSocket flags.
- IsDisconnected()
+ If you use LastCount(), it will always return @a nbytes.
- LastCount()
-
- LastError()
-
- IsOk()
-
- SaveState()
-
- RestoreState()
- */
-
-
- /**
- This function unreads a buffer. That is, the data in the buffer is put back
- in the incoming queue. This function is not affected by wxSocket flags.
- If you use LastCount(), it will always return @e nbytes.
If you use Error(), it will always return @false.
@param buffer
@see Error(), LastCount(), LastError()
*/
- wxSocketBase Unread(const void* buffer, wxUint32 nbytes);
+ wxSocketBase& Unread(const void* buffer, wxUint32 nbytes);
/**
- This function waits until any of the following conditions is @true:
+ Wait for any socket event.
- The socket becomes readable.
- The socket becomes writable.
- An ongoing connection request has completed (wxSocketClient only)
- An incoming connection request has arrived (wxSocketServer only)
- The connection has been closed.
- Note that it is recommended to use the individual Wait functions
- to wait for the required condition, instead of this one.
+ Possible socket events are:
+ @li The socket becomes readable.
+ @li The socket becomes writable.
+ @li An ongoing connection request has completed (wxSocketClient only)
+ @li An incoming connection request has arrived (wxSocketServer only)
+ @li The connection has been closed.
+
+ Note that it is recommended to use the individual @b WaitForXXX()
+ functions to wait for the required condition, instead of this one.
@param seconds
Number of seconds to wait.
If -1, it will wait for the default timeout,
- as set with SetTimeout.
+ as set with SetTimeout().
@param millisecond
Number of milliseconds to wait.
- @return Returns @true when any of the above conditions is satisfied,
- @false if the timeout was reached.
+ @return
+ @true when any of the above conditions is satisfied or @false if the
+ timeout was reached.
- @see InterruptWait(), wxSocketServer::WaitForAccept,
+ @see InterruptWait(), wxSocketServer::WaitForAccept(),
WaitForLost(), WaitForRead(),
- WaitForWrite(), wxSocketClient::WaitOnConnect
+ WaitForWrite(), wxSocketClient::WaitOnConnect()
*/
bool Wait(long seconds = -1, long millisecond = 0);
/**
- This function waits until the connection is lost. This may happen if
- the peer gracefully closes the connection or if the connection breaks.
+ Wait until the connection is lost.
+
+ This may happen if the peer gracefully closes the connection or if the
+ connection breaks.
@param seconds
Number of seconds to wait.
If -1, it will wait for the default timeout,
- as set with SetTimeout.
+ as set with SetTimeout().
@param millisecond
Number of milliseconds to wait.
@return Returns @true if the connection was lost, @false if the timeout
- was reached.
+ was reached.
@see InterruptWait(), Wait()
*/
bool WaitForLost(long seconds = -1, long millisecond = 0);
/**
- This function waits until the socket is readable. This might mean that
- queued data is available for reading or, for streamed sockets, that
- the connection has been closed, so that a read operation will complete
- immediately without blocking (unless the @b wxSOCKET_WAITALL flag
+ Wait until the socket is readable.
+
+ This might mean that queued data is available for reading or, for streamed
+ sockets, that the connection has been closed, so that a read operation will
+ complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
is set, in which case the operation might still block).
+ Notice that this function should not be called if there is already data
+ available for reading on the socket.
+
@param seconds
Number of seconds to wait.
If -1, it will wait for the default timeout,
- as set with SetTimeout.
+ as set with SetTimeout().
@param millisecond
Number of milliseconds to wait.
bool WaitForRead(long seconds = -1, long millisecond = 0);
/**
- This function waits until the socket becomes writable. This might mean that
- the socket is ready to send new data, or for streamed sockets, that the
- connection has been closed, so that a write operation is guaranteed to
- complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
+ Wait until the socket becomes writable.
+
+ This might mean that the socket is ready to send new data, or for streamed
+ sockets, that the connection has been closed, so that a write operation is
+ guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
in which case the operation might still block).
+ Notice that this function should not be called if the socket is already
+ writable.
+
@param seconds
Number of seconds to wait.
If -1, it will wait for the default timeout,
- as set with SetTimeout.
+ as set with SetTimeout().
@param millisecond
Number of milliseconds to wait.
bool WaitForWrite(long seconds = -1, long millisecond = 0);
/**
- This function writes a buffer of @a nbytes bytes to the socket.
- Use LastCount() to verify the number of bytes actually written.
+ Write up to the given number of bytes to the socket.
+
+ Use LastWriteCount() to verify the number of bytes actually written.
+
Use Error() to determine if the operation succeeded.
@param buffer
@return Returns a reference to the current object.
- @see Error(), LastError(), LastCount(),
- SetFlags()
+ @remarks
+
+ The exact behaviour of Write() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags().
+
+ @see Error(), LastError(), LastWriteCount(), SetFlags()
*/
- wxSocketBase Write(const void* buffer, wxUint32 nbytes);
+ wxSocketBase& Write(const void* buffer, wxUint32 nbytes);
/**
- This function writes a buffer of @a nbytes bytes from the socket, but it
- writes a short header before so that ReadMsg()
- knows how much data should it actually read. So, a buffer sent with WriteMsg
- @b must be read with ReadMsg. This function always waits for the entire
- buffer to be sent, unless an error occurs.
- Use LastCount() to verify the number of bytes actually written.
+ Sends a buffer which can be read using ReadMsg().
+
+ WriteMsg() sends a short header before the data so that ReadMsg()
+ knows how much data should be actually read.
+
+ This function always waits for the entire buffer to be sent, unless an
+ error occurs.
+
+ Use LastWriteCount() to verify the number of bytes actually written.
+
Use Error() to determine if the operation succeeded.
@param buffer
Number of bytes to send.
@return Returns a reference to the current object.
+
+ @remarks
+
+ WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and
+ it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of
+ WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation,
+ see SetFlags().
+ For thread safety, in case ReadMsg() and WriteMsg() are called in
+ different threads, it is a good idea to call
+ @code SetFlags(wxSOCKET_WAITALL|wx_SOCKET_BLOCK) @endcode before the
+ first calls to ReadMsg() and WriteMsg() in different threads, as each
+ of these functions calls SetFlags() which performs read/modify/write.
+ By setting these flags before the multi-threading, it will ensure that
+ they don't get reset by thread race conditions.
+
+ @see Error(), LastError(), LastWriteCount(), SetFlags(), ReadMsg()
+
+ */
+ wxSocketBase& WriteMsg(const void* buffer, wxUint32 nbytes);
+
+ //@}
+
+
+ /**
+ @name Handling Socket Events
*/
- wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes);
+ //@{
+
+ /**
+ Returns a pointer of the client data for this socket, as set with
+ SetClientData()
+ */
+ void* GetClientData() const;
+
+ /**
+ According to the @a notify value, this function enables
+ or disables socket events. If @a notify is @true, the events
+ configured with SetNotify() will
+ be sent to the application. If @a notify is @false; no events
+ will be sent.
+ */
+ void Notify(bool notify);
+
+ /**
+ Sets user-supplied client data for this socket. All socket events will
+ contain a pointer to this data, which can be retrieved with
+ the wxSocketEvent::GetClientData() function.
+ */
+ void SetClientData(void* data);
+
+ /**
+ Sets an event handler to be called when a socket event occurs. The
+ handler will be called for those events for which notification is
+ enabled with SetNotify() and
+ Notify().
+
+ @param handler
+ Specifies the event handler you want to use.
+ @param id
+ The id of socket event.
+
+ @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
+ */
+ void SetEventHandler(wxEvtHandler& handler, int id = -1);
+
+ /**
+ Specifies which socket events are to be sent to the event handler.
+ The @a flags parameter may be combination of flags ORed together. The
+ following flags can be used:
+
+ @beginFlagTable
+ @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT.
+ @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT.
+ @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION.
+ @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST.
+ @endFlagTable
+
+ For example:
+
+ @code
+ sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
+ sock.Notify(true);
+ @endcode
+
+ In this example, the user will be notified about incoming socket data and
+ whenever the connection is closed.
+
+ For more information on socket events see @ref wxSocketEventFlags .
+ */
+ void SetNotify(wxSocketEventFlags flags);
+
+ /**
+ Returns the native socket descriptor.
+
+ This is intended to use with rarely used specific platform features
+ that can only be accessed via the actual socket descriptor.
+
+ Do not use this for reading or writing data from or to the socket as
+ this would almost surely interfere with wxSocket code logic and result
+ in unexpected behaviour.
+
+ The socket must be successfully initialized, e.g. connected for client
+ sockets, before this method can be called.
+
+ @return Returns the native socket descriptor.
+
+ @since 2.9.5
+ */
+ wxSOCKET_T GetSocket() const;
+
+ //@}
};
/**
@class wxDatagramSocket
+ @todo docme
@library{wxnet}
- @category{FIXME}
-
- @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount,
- wxSocketBase::SetFlags,
+ @category{net}
*/
class wxDatagramSocket : public wxSocketBase
{
/**
Constructor.
+ @param addr
+ The socket address.
@param flags
- Socket flags (See wxSocketBase::SetFlags)
+ Socket flags (See wxSocketBase::SetFlags()).
*/
- wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE);
+ wxDatagramSocket(const wxSockAddress& addr,
+ wxSocketFlags flags = wxSOCKET_NONE);
/**
- Destructor. Please see wxSocketBase::Destroy.
+ Destructor. Please see wxSocketBase::Destroy().
*/
- ~wxDatagramSocket();
+ virtual ~wxDatagramSocket();
/**
- This function reads a buffer of @a nbytes bytes from the socket.
- Use wxSocketBase::LastCount to verify the number of bytes actually read.
- Use wxSocketBase::Error to determine if the operation succeeded.
-
- @param address
- Any address - will be overwritten with the address of the peer that sent
- that data.
- @param buffer
- Buffer where to put read data.
- @param nbytes
- Number of bytes.
-
- @return Returns a reference to the current object, and the address of
- the peer that sent the data on address param.
+ Write a buffer of @a nbytes bytes to the socket.
- @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount,
- wxSocketBase::SetFlags,
- */
- wxDatagramSocket ReceiveFrom(wxSockAddress& address,
- void* buffer,
- wxUint32 nbytes);
-
- /**
- This function writes a buffer of @a nbytes bytes to the socket.
- Use wxSocketBase::LastCount to verify the number of bytes actually wrote.
- Use wxSocketBase::Error to determine if the operation succeeded.
+ Use wxSocketBase::LastWriteCount() to verify the number of bytes actually wrote.
+ Use wxSocketBase::Error() to determine if the operation succeeded.
@param address
The address of the destination peer for this data.
Number of bytes.
@return Returns a reference to the current object.
+
+ @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
*/
- wxDatagramSocket SendTo(const wxSockAddress& address,
- const void* buffer,
- wxUint32 nbytes);
+ wxDatagramSocket& SendTo(const wxSockAddress& address,
+ const void* buffer, wxUint32 nbytes);
};
projects / wxWidgets.git / blobdiff