/////////////////////////////////////////////////////////////////////////////
// Name: socket.h
-// Purpose: interface of wxIPV4address
+// Purpose: interface of wxIP*address, wxSocket* classes
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
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>)
+ in dot notation(<tt>a.b.c.d</tt>).
- @return @true on success, @false if something goes wrong (invalid hostname or
- invalid IP address).
+ @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();
+ 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).
correctly handle multi-homed hosts and avoid other small problems.
@return @true on success, @false if something went wrong.
-
*/
bool LocalHost();
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 @true on success, @false if something goes wrong (invalid @a service).
*/
- bool Service(unsigned short service);
+ bool Service(unsigned short service) = 0;
/**
Returns the current service.
*/
- unsigned short Service();
+ unsigned short Service() const = 0;
};
/**
@class wxSocketServer
+ @todo describe me.
+
@library{wxnet}
@category{net}
*/
@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
@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.
+ 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.
@param seconds
Number of seconds to wait. If -1, it will wait for the default
@return @true on success, @false if something went wrong.
*/
- virtual bool AnyAddress();
+ virtual bool AnyAddress() = 0;
/**
Internally, this is the same as setting the IP address to @b INADDR_BROADCAST.
@return @true on success, @false if something went wrong.
*/
- virtual bool BroadcastAddress();
+ virtual bool BroadcastAddress() = 0;
/**
Set the address to hostname, which can be a host name or an IP-style address
@return @true on success, @false if something goes wrong (invalid
hostname or invalid IP address).
*/
- virtual bool Hostname(const wxString& hostname);
+ virtual bool Hostname(const wxString& hostname) = 0;
/**
Returns the hostname which matches the IP address.
*/
- virtual wxString Hostname();
+ virtual wxString Hostname() const = 0;
/**
Returns a wxString containing the IP address.
*/
- virtual wxString IPAddress();
+ 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();
+ virtual bool IsLocalHost() const = 0;
/**
Set address to localhost.
@return @true on success, @false if something went wrong.
*/
- virtual bool LocalHost();
+ virtual bool LocalHost() = 0;
/**
Set the port to that corresponding to the specified service.
@return @true on success, @false if something goes wrong (invalid @a service).
*/
- virtual bool Service(const wxString& service);
+ virtual bool Service(const wxString& service) = 0;
/**
Set the port to that corresponding to the specified service.
@return @true on success, @false if something goes wrong (invalid @a service).
*/
- virtual bool Service(unsigned short service);
+ virtual bool Service(unsigned short service) = 0;
/**
Returns the current service.
*/
- virtual unsigned short Service();
+ virtual unsigned short Service() const = 0;
};
/**
@class wxSocketClient
+ @todo describe me.
+
@library{wxnet}
@category{net}
*/
/**
Destructor. Please see wxSocketBase::Destroy().
*/
- ~wxSocketClient();
+ virtual ~wxSocketClient();
/**
Connects to a server using the specified address.
If @a wait is @true, Connect() will wait until the connection
- completes. @b Warning: This will block the GUI.
+ completes.
+
+ @warning: This method 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,
If @true, waits for the connection to complete.
@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()
*/
- bool Connect(const wxSockAddress& address, bool wait = true);
+ virtual bool Connect(const wxSockAddress& address, bool wait = true);
/**
Connects to a server using the specified address.
If @true, waits for the connection to complete.
@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()
*/
/**
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 wxSocketBase::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 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
+ @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);
};
/**
Default destructor.
*/
- ~wxSockAddress();
+ virtual ~wxSockAddress();
/**
Delete all informations about the address.
*/
- void Clear();
+ virtual void Clear();
/**
Returns the length of the socket address.
Gets the client data of the socket which generated this event, as
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;
/**
+ @anchor wxSocketEventFlags
+
wxSocket Event Flags.
A brief note on how to use these events:
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.
+ - @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.
*/
enum
{
/**
@class wxSocketBase
-
wxSocketBase is the base class for all socket-related objects, and it
defines all basic IO functionality.
- @b Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x)
+ @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 @b wxSocketBase::Initialize() (undocumented) from the main thread before
- creating any sockets - in wxApp::OnInit() for example.
+ thread, call @b 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.
- @library{wxnet}
- @category{net}
-
- <b>wxSocket events:</b>
- @beginFlagTable
- @flag{wxSOCKET_INPUT}
- There is data available for reading.
- @flag{wxSOCKET_OUTPUT}
- The socket is ready to be written to.
- @flag{wxSOCKET_CONNECTION}
- Incoming connection request (server), or successful connection
- establishment (client).
- @flag{wxSOCKET_LOST}
- The connection has been closed.
- @endFlagTable
-
@beginEventTable{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, @sample{sockets},
@ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
*/
*/
bool GetPeer(wxSockAddress& addr) const;
+ /**
+ Return the socket timeout in seconds.
+
+ The timeout can be set using SetTimeout() and is 10 minutes by default.
+ */
+ long GetTimeout() const;
+
/**
Returns @true if the socket is connected.
*/
cases.
@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 IsOk() const;
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).
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().
+ 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()
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
socket destruction), so you don't need to use it in these cases.
@see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
- wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
+ wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
*/
void InterruptWait();
@return Returns a reference to the current object.
@remarks
-
- The exact behaviour of Peek() depends on the combination of flags being used.
- For a detailed explanation, see SetFlags()
+ The exact behaviour of Peek() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags()
@see Error(), LastError(), LastCount(), SetFlags()
*/
@return Returns a reference to the current object.
@remarks
-
- The exact behaviour of Read() depends on the combination of flags being used.
- For a detailed explanation, see SetFlags()
+ The exact behaviour of Read() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags()
@see Error(), LastError(), LastCount(),
SetFlags()
@return Returns a reference to the current object.
@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().
+ 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().
@see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
*/
Number of milliseconds to wait.
@return Returns @true when any of the above conditions is satisfied,
- @false if the timeout was reached.
+ @false if the timeout was reached.
@see InterruptWait(), wxSocketServer::WaitForAccept(),
WaitForLost(), WaitForRead(),
Number of milliseconds to wait.
@return Returns @true if the connection was lost, @false if the timeout
- was reached.
+ was reached.
@see InterruptWait(), Wait()
*/
/**
@class wxDatagramSocket
+ @todo docme
+
@library{wxnet}
@category{net}
*/
/**
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().
*/
- ~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.
-
- @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
- */
- wxDatagramSocket ReceiveFrom(wxSockAddress& address,
- void* buffer, wxUint32 nbytes);
+ virtual ~wxDatagramSocket();
/**
This function writes a buffer of @a nbytes bytes to the socket.
@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