|
OpenTop 1.3 | |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | Cross-Platform C++ | ||||
SUMMARY: CONSTRUCTOR | METHOD | DETAIL: CONSTRUCTOR | METHOD |
#include "ot/net/Socket.h"
The Socket class manages a socket handle which is provided by the underlying operating system. This handle is represented by a SocketDescriptor, which enables OpenTop to close the socket handle when it is no longer required.
When a Socket is created, it can be connected to a specific end-point by using an appropriate constructor, or it can be connected after construction using one of the connect() methods.
Data is sent over the Socket connection using an OutputStream returned from getOutputStream() and received using an InputStream returned from getInputStream().
The actual work of the Socket is performed by an instance of the SocketImpl class. Instances of SocketImpl are created using a factory class: SocketImplFactory. An application can change the socket factory that creates the socket implementation by calling SetSocketImplFactory() on this class. The default socket factory creates plain SocketImpl instances which do not perform any special processing.
Constructor/Destructor Summary | |
Socket() Creates an unconnected socket. | |
Socket(SocketImpl* pImpl) Protected constructor that creates a Socket using the passed SocketImpl. | |
Socket(InetAddress* pAddress, int port) Creates a Socket and connects it to the specified port on the network host designated by the provided InetAddress. | |
Socket(const String& host, int port) Creates a Socket that is connected to a specified host name and port. | |
Socket(InetAddress* pAddress, int port, InetAddress* pLocalAddr, int localPort) Creates a Socket and connects it to the specified remote port on the network host designated by the provided InetAddress. | |
Socket(const String& host, int port, InetAddress* pLocalAddr, int localPort) |
Method Summary | |
virtual void |
close() Closes the Socket and releases any system resources associated with it. |
virtual void |
connect(InetAddress* pAddress, int port) Connects an unconnected socket to a port on a remote host. |
virtual void |
connect(const String& host, int port) Connects an unconnected socket to a port on a remote host. |
virtual void |
connect(InetAddress* pAddress, int port, size_t timeoutMS) Connects an unconnected socket to a port on a remote host. |
virtual bool |
getAutoClose() const Tests if auto_close is enabled. |
virtual RefPtr< InetAddress > |
getInetAddress() const Returns an InetAddress representing the remote host to which this Socket is connected. |
virtual RefPtr< InputStream > |
getInputStream() const Returns an InputStream that can be used to read data from this Socket. |
virtual bool |
getKeepAlive() const Tests if SO_KEEPALIVE is enabled. |
virtual RefPtr< InetAddress > |
getLocalAddress() const Returns an InetAddress representing the local address to which this Socket is bound. |
virtual int |
getLocalPort() const Returns the local port number to which this socket is bound. |
virtual RefPtr< OutputStream > |
getOutputStream() const Returns an OutputStream that can be used to write data to this Socket. |
virtual int |
getPort() const Returns the remote port to which this socket is connected. |
virtual int |
getReceiveBufferSize() const Returns the SO_RVCBUF option for this Socket, which is the size of the buffer used by the operating system to hold received data before it is read by the application. |
virtual int |
getSendBufferSize() const Returns the value of the SO_SNDBUF option for this Socket, which is the size of the buffer used by the operating system to store output data from the application before it is sent to (and acknowledged by) the connected host. |
static RefPtr< SocketImplFactory > |
GetSocketImplFactory() Returns the static object that is the SocketImplFactory for client sockets. |
virtual int |
getSoLinger() const Returns the setting for the SO_LINGER option for this Socket. |
virtual size_t |
getSoTimeout() const Returns the value of the SO_TIMEOUT pseudo option. |
virtual bool |
getTcpNoDelay() const Tests if the TCP_NODELAY option is enabled for this Socket. |
virtual bool |
isClosed() Tests if this socket is closed. |
virtual bool |
isConnected() Tests the connected status of this Socket. |
virtual void |
setAutoClose(bool bEnable) Enables/disables the auto_close feature. |
virtual void |
setKeepAlive(bool bEnable) Enables/disables the SO_KEEPALIVE option for this Socket. |
virtual void |
setReceiveBufferSize(size_t size) Sets the SO_RCVBUF option for this Socket, which is the size of the buffer used by the operating system to hold received data before it is read by the application. |
virtual void |
setSendBufferSize(size_t size) Sets the SO_SNDBUF option for this Socket, which is the size of the buffer used by the operating system to store output data from the application before it is sent to (and acknowledged by) the connected host. |
static void |
SetSocketImplFactory(SocketImplFactory* pFac) Sets the client socket implementation factory for the application. |
virtual void |
setSoLinger(bool bEnable, size_t linger) Sets the SO_LINGER option for this Socket. |
virtual void |
setSoTimeout(size_t timeoutMS) Enables/disables the SO_TIMEOUT pseudo option. |
virtual void |
setTcpNoDelay(bool bEnable) Enables/disables the TCP_NODELAY option for this Socket. |
virtual void |
shutdownInput() Shuts down this Socket for input operations. |
virtual void |
shutdownOutput() Shuts down this Socket for output operations. |
virtual String |
toString() const Returns a string representation of this Socket. |
Methods inherited from class ot::ManagedObject |
addRef, getRefCount, onFinalRelease, operator=, release |
Constructor/Destructor Detail |
Socket()
Before the socket can be used to communicate with an end-point, it must first be connected using connect().
SocketException
- protected Socket(SocketImpl* pImpl)
NullPointerException
- Socket(InetAddress* pAddress, int port)
SocketException
- NullPointerException
- Socket(const String& host, int port)
host
- UnknownHostException
- SocketException
- Socket(InetAddress* pAddress, int port, InetAddress* pLocalAddr, int localPort)
If pLocalAddr is null, the socket is bound to any interface on the local host. If localPort is 0, the operating system chooses an unused local port number.
NullPointerException
- SocketException
- Socket(const String& host, int port, InetAddress* pLocalAddr, int localPort)
Method Detail |
virtual void close()
Generally, applications will not need to call this function because the socket is automatically closed when the reference-count of the SocketDescriptor is decremented to zero.
Subsequent read or write operations will fail with an IOException except when using buffered streams, which may not register that the socket has been closed until the next time the buffer is refreshed or flushed.
SocketException
- virtual void connect(InetAddress* pAddress, int port)
pAddress
- port
- NullPointerException
- SocketException
- virtual void connect(const String& host, int port)
host
- port
- UnknownHostException
- SocketException
- virtual void connect(InetAddress* pAddress, int port, size_t timeoutMS)
pAddress
- port
- timeoutMS
- NullPointerException
- SocketException
- SocketTimeoutException
- virtual bool getAutoClose() const
virtual RefPtr< InetAddress > getInetAddress() const
virtual RefPtr< InputStream > getInputStream() const
virtual bool getKeepAlive() const
SocketException
- virtual RefPtr< InetAddress > getLocalAddress() const
virtual int getLocalPort() const
virtual RefPtr< OutputStream > getOutputStream() const
virtual int getPort() const
virtual int getReceiveBufferSize() const
SocketException
- virtual int getSendBufferSize() const
SocketException
- static RefPtr< SocketImplFactory > GetSocketImplFactory()
virtual int getSoLinger() const
SocketException
- virtual size_t getSoTimeout() const
virtual bool getTcpNoDelay() const
SocketException
- virtual bool isClosed()
virtual bool isConnected()
virtual void setAutoClose(bool bEnable)
bEnable
- SocketException
- virtual void setKeepAlive(bool bEnable)
Note that the time interval between heartbeat packets is controlled by the operating system, and may be as long as 2 hours.
bEnable
- SocketException
- virtual void setReceiveBufferSize(size_t size)
The SO_RCVBUF option can only be set before a client socket is connected to a remote host (buffer sizes are negotiated between hosts when the connection is established). A SocketException will be thrown if this method is called on a connected client Socket.
size
- SocketException
- virtual void setSendBufferSize(size_t size)
The SO_SNDBUF option can only be set before a client socket is connected to a remote host (buffer sizes are negotiated between hosts when the connection is established). A SocketException will be thrown if this method is called on a connected client Socket.
size
- SocketException
- static void SetSocketImplFactory(SocketImplFactory* pFac)
An application should only call this function if it wishes to employ a customized SocketImpl class.
To ensure that the passed object exists for as long as the application needs it, the SocketImplFactory object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination. This absolves the application from having to manage the lifetime of the passed object. For example, the following code is perfectly valid and does not cause a memory leak:-
int main(int argc, char* argv[]) { SystemMonitor _monitor(); // ensures clean termination // register a customized socket implementation factory Socket::SetSocketImplFactory(new MySocketImplFactory); ... }
pFac
- NullPointerException
- virtual void setSoLinger(bool bEnable, size_t linger)
The SO_LINGER option specifies how the close() function operates. By default, close() returns immediately, but if there is any data still remaining in the socket's send buffer, the operating system will attempt to deliver that data to the connected host.
When the SO_LINGER option is enabled, calls to close() will wait for up to a specified length of time until that data has been sent and acknowledged.
bEnable
- linger
- SocketException
- virtual void setSoTimeout(size_t timeoutMS)
timeoutMS
- virtual void setTcpNoDelay(bool bEnable)
bEnable
- SocketException
- virtual void shutdownInput()
SocketException
- virtual void shutdownOutput()
SocketException
- virtual String toString() const
|
OpenTop 1.3 | |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | Cross-Platform C++ | ||||
SUMMARY: CONSTRUCTOR | METHOD | DETAIL: CONSTRUCTOR | METHOD |