TCP/IP socket, reliable stream. More...

Inheritance diagram for MStreamSocket:

Classes
class	OperationHandler
	Generic class that can be used for cancellation of open socket operation. More...

Public Member Functions
	MStreamSocket (SocketHandleType socketHandle=InvalidSocket)
	Constructor that creates socket based on existing socket handle. More...

virtual	~MStreamSocket ()
	Destructor, destroys the socket object and never throws an exception. More...

virtual MStdString	GetName () const
	Return a representative name of a socket stream. More...

virtual MStdString	GetPeerSocketName () const
	Get the IP address for the peer socket. More...

virtual unsigned	GetPeerSocketPort () const
	Get the port for the peer socket. More...

void	SetLinger (bool doLinger, int lingerTime)
	Set Linger socket option. More...

void	Connect (unsigned port, const MStdString &address)
	Create client socket that connects to the server. More...

void	ConnectInterruptible (unsigned port, const MStdString &address, OperationHandler *oph)
	Create client socket that connects to the server. More...

void	ConnectWithProxy (unsigned port, const MStdString &address, const MStdString &proxyAddress)
	Create client socket that connects to the server through a SOCKS proxy. More...

void	ConnectWithProxyInterruptible (unsigned port, const MStdString &address, const MStdString &proxyAddress, OperationHandler *oph)
	Create client socket that connects to the server through a SOCKS proxy. More...

void	Listen (unsigned backlog=5)
	Listen for incoming socket connections. More...

void	Accept (MStreamSocket &socket)
	Accept the connection by the server and assign a new connection with the client. More...

bool	TimedAccept (MStreamSocket &socket, unsigned timeout)
	Accept the connection by the server and assign a new connection with the client, or timeout. More...

void	Swap (MStreamSocket &other)
	Swap this socket and the given socket by exchanging their handles and other properties. More...

virtual void	ClearInputBuffer ()
	Clear the input buffer by reading all the available data from the socket, if any are there. More...

unsigned	Recv (char *buffer, unsigned length, int flags)
	Analog of the standard socket function recv. More...

unsigned	Send (const char *buffer, unsigned length, int flags)
	Send the buffer through the socket, standard socket function send. More...

virtual unsigned	GetBytesReadyToRead () const
	The number of bytes in the receive buffer that can be read immediately. More...


unsigned	GetSendTimeout () const

void	SetSendTimeout (unsigned milliseconds)


bool	GetNoDelay () const

void	SetNoDelay (bool)


int	GetSendBufferSize () const

void	SetSendBufferSize (int)


int	GetReceiveBufferSize () const

void	SetReceiveBufferSize (int size)

Public Member Functions inherited from MStreamSocketBase
MStdString	GetLocalSocketName () const
	Get the local name for this socket. More...

unsigned	GetLocalSocketPort () const
	Get the local port for a socket. More...

void	Bind (unsigned port, const MStdString &address=MVariant::s_emptyString)
	Bind a server socket. More...

bool	WaitToReceive (unsigned timeout=(unsigned) TimeoutInfinite) const
	Waits the time given in milliseconds for the input data to arrive. More...

bool	WaitToSend (unsigned timeout=(unsigned) TimeoutInfinite) const
	Waits the time given in milliseconds for the output buffer to become not full. More...

bool	IsInputBufferEmpty () const
	Whether the input buffer has any data. More...

int	GetSockOpt (int level, int option)
	Get socket option as integer, access to the standard socket call. More...

MByteString	GetSockOptBytes (int level, int option, unsigned bufferSize)
	Get socket option as byte string, access to the standard socket call. More...

void	SetSockOpt (int level, int option, const MVariant &value)
	Set socket option, access to the standard socket call. More...

SocketHandleType	GetSocketHandle () const

void	SetSocketHandle (SocketHandleType)

unsigned	GetReceiveTimeout () const

void	SetReceiveTimeout (unsigned milliseconds)

Public Member Functions inherited from MStream
virtual	~MStream ()
	Closes the stream and destroys the object. More...

bool	IsOpen () const
	Whether the stream object is successfully open. More...

unsigned	GetFlags () const
	Return flags associated with stream. More...

MByteString	Read (unsigned count)
	Reads a byte string of a given length from the stream. More...

MByteString	ReadAvailable (unsigned count)
	Reads a byte string up to a given length from the stream. More...

MByteString	ReadAll ()
	Reads all bytes available in stream. More...

void	ReadBytes (char *buffer, unsigned count)
	Reads a byte buffer of a given length from the stream. More...

unsigned	ReadAvailableBytes (char *buffer, unsigned count)
	Reads a byte buffer up to a given length from the stream. More...

MVariant	ReadLine ()
	Read one line from text file. More...

bool	ReadOneLine (MStdString &line)
	Read one line from text file, return false at end of file. More...

MStdStringVector	ReadAllLines ()
	Read all lines from text file. More...

void	Skip (unsigned count)
	Skips over and discards specified number of bytes of data from this stream. More...

void	WriteByte (Muint8 byte)
	Writes a byte to the current position in the stream and advances the position by one byte. More...

void	WriteChar (char c)
	Writes a char to the current position in the stream and advances the position by one byte. More...

void	Write (const MByteString &bytes)
	Writes a given byte string to the current position in the stream and advances the position. More...

void	WriteBytes (const char *bytes, unsigned count)
	Writes a given byte buffer to the current position in the stream and advances the position. More...

void	WriteChars (const char *chars)
	Writes a given zero terminated character string to the current position in the stream and advances the position. More...

void	WriteLine (const MStdString &str)
	Write a line into file. More...

void	WriteAllLines (const MStdStringVector &lines)
	Write given lines into file. More...

void	WriteFormat (MConstChars format,...)
	Write a formatted string into a file. More...

void	WriteFormatVA (MConstChars format, va_list args)
	Write a formatted string into a file using va_list. More...

void	Flush ()
	Causes any buffered data to be written into stream. More...

void	Close ()
	Flushes and closes the current stream and releases any resources. More...

MStdString	GetKey () const

void	SetKey (const MStdString &)

unsigned	GetPosition () const

void	SetPosition (unsigned)

unsigned	GetSize () const

void	SetSize (unsigned)

MVariant	ReadByte ()

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

virtual unsigned	GetEmbeddedSizeof () const
	For embedded object types, return the size of the class. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Call the object service with parameters, given as variant vector. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists.

virtual MVariant	GetProperty (const MStdString &name) const
	Get the property value using name of the property. More...

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Set the property using name of the property, and value. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Additional Inherited Members
Public Types inherited from MStreamSocketBase
typedef int	SocketHandleType

Public Types inherited from MStream
enum	OpenFlags { FlagReadOnly = 0x0001, FlagWriteOnly = 0x0002, FlagReadWrite = 0x0003, FlagText = 0x00010, FlagBuffered = 0x0020 }
	Flags that set modes of stream manipulation. More...

Static Public Member Functions inherited from MStreamSocketBase
static MStdString	GetLocalName ()
	Returns the standard host name for the local machine. More...

static MStdString	GetLocalAddress ()
	Returns the host address for the local machine. More...

static MByteString	AddressToBinary (const MStdString &addr)
	Convert a string with IPv4 or IPv6 IP address into a binary form. More...

static MStdString	BinaryToAddress (const MByteString &addr)
	Convert a binary form of IPv4 or IPv6 address into a string. More...

static bool	IsAddressLocalIPv4 (const MStdString &address)
	True if the given string represents an IPv4 address. More...

static bool	IsAddressLocalIPv6 (const MStdString &address)
	True if the given string represents an IPv6 address. More...

Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Static Public Attributes inherited from MStreamSocketBase
static const SocketHandleType	InvalidSocket = (SocketHandleType)(~0)
	Value of socket handle that corresponds to uninitialized or invalid socket.

static const int	SocketErrorStatus = -1
	Return value that corresponds to uninitialized or invalid socket.

static const unsigned	TimeoutInfinite = (unsigned)-1
	Timeout that represents infinity. More...

static const unsigned	TimeoutDefault = 60000
	Default socket read timeout in milliseconds. More...

Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Protected Member Functions inherited from MStreamSocketBase
	MStreamSocketBase (SocketHandleType socketHandle=InvalidSocket)
	Constructor that creates socket based on the existing socket handle. More...

virtual	~MStreamSocketBase ()
	Destructor, destroys the socket object and never throws an exception. More...

Protected Member Functions inherited from MStream
	MStream ()
	Default constructor, called from children of stream.

Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Detailed Description

TCP/IP socket, reliable stream.

The services below can throw MESocketError in the event of an erroneous socket operation.

Implementation detail: Windows does not support SO_RCVTIMEO socket option for synchronous ports, and read timeout is supported through the call to select. The timeout value in milliseconds is given to services that support timeouts.

Constructor & Destructor Documentation

MStreamSocket::MStreamSocket ( SocketHandleType socketHandle = InvalidSocket )

explicit

Constructor that creates socket based on existing socket handle.

This is a C++ only method that is convenient for cases when the socket is open by any means other than the socket stream object.

Parameters

socketHandle Handle to use by the socket. When handle is an invalid socket value, or not present, the socket will not be opened.

virtual MStreamSocket::~MStreamSocket ( )

virtual

Destructor, destroys the socket object and never throws an exception.

Use Close if there is a need to report any socket related exceptions.

Member Function Documentation

void MStreamSocket::Accept ( MStreamSocket & socket )

Accept the connection by the server and assign a new connection with the client.

Parameters

socket The uninitialized socket object to which the connection will be accepted.

See also: TimedAccept method that can timeout if no connections arrived.

virtual void MStreamSocket::ClearInputBuffer ( )

virtual

Clear the input buffer by reading all the available data from the socket, if any are there.

Precondition: The socket is alive, other read-related errors possible.

Implements MStreamSocketBase.

void MStreamSocket::Connect	(	unsigned	port,
		const MStdString &	address
	)

inline

Create client socket that connects to the server.

Parameters

port	Port to connect to.
address	IP address or a DNS name of the server to which the connection has to be made.

See also: ConnectWithProxy - Connect to a socket through SOCKS proxy.

void MStreamSocket::ConnectInterruptible	(	unsigned	port,
		const MStdString &	address,
		OperationHandler *	oph
	)

Create client socket that connects to the server.

Parameters

port	Port to connect to.
address	IP address or a DNS name of the server to which the connection has to be made.
oph	Optional pointer to an operation handler that is capable of canceling the opening.

See also: ConnectWithProxy - Connect to a socket through SOCKS proxy.

void MStreamSocket::ConnectWithProxy	(	unsigned	port,
		const MStdString &	address,
		const MStdString &	proxyAddress
	)

inline

Create client socket that connects to the server through a SOCKS proxy.

Supported are SOCKS4, SOCKS4+ and SOCKS5 proxy servers.

Parameters

port	Port to connect to.
address	IP address or a DNS name of the server to which the connection has to be made.
proxyAddress	Proxy address in one of the following forms: "" means no proxy shall be used, connect directly to the given host. "IP_ADDRESS:PORT" such as "10.0.0.123:345" for SOCKS4 proxy. "IP_ADDRESS:PORT" such as "10.0.0.123:345" for SOCKS4 proxy. "host.name:PORT" such as "example.com:678" for SOCKS4+ proxy. "user:host.name:PORT" such as "dennis_richie:example.com:678" for SOCKS5 proxy without password. "user@password:host.name:PORT" such as "dennis_richie@unix:example.com:678" for SOCKS5 proxy with password.

void MStreamSocket::ConnectWithProxyInterruptible	(	unsigned	port,
		const MStdString &	address,
		const MStdString &	proxyAddress,
		OperationHandler *	oph
	)

Create client socket that connects to the server through a SOCKS proxy.

Supported are SOCKS4, SOCKS4+ and SOCKS5 proxy servers.

Parameters

port	Port to connect to.
address	IP address or a DNS name of the server to which the connection has to be made.
proxyAddress	Proxy address in one of the following forms: "" means no proxy shall be used, connect directly to the given host. "IP_ADDRESS:PORT" such as "10.0.0.123:345" for SOCKS4 proxy. "IP_ADDRESS:PORT" such as "10.0.0.123:345" for SOCKS4 proxy. "host.name:PORT" such as "example.com:678" for SOCKS4+ proxy. "user:host.name:PORT" such as "dennis_richie:example.com:678" for SOCKS5 proxy without password. "user@password:host.name:PORT" such as "dennis_richie@unix:example.com:678" for SOCKS5 proxy with password.
oph	Pointer to an operation handler that is capable of canceling the opening. If null, this call is equivalent to ConnectWithProxy.

virtual unsigned MStreamSocket::GetBytesReadyToRead ( ) const

virtual

The number of bytes in the receive buffer that can be read immediately.

Returns the number of bytes ready to be read from socket.

Precondition: The connection is alive, otherwise the connection-specific exception is thrown.

See also: MStreamSocketBase::WaitToReceive - Waits the specified time for the input data to arrive.

Implements MStreamSocketBase.

virtual MStdString MStreamSocket::GetName ( ) const

virtual

Return a representative name of a socket stream.

This method overwrites the parent implementation and gives descriptive information about the socket. For example, it can return client host name or IP address, and its port number. The particular information is not guaranteed to have the same format.

Implements MStream.

bool MStreamSocket::GetNoDelay ( ) const

No Delay socket option.

Having No Delay true disables Nagle algorithm, which might cause an increase in network traffic, with smaller than needed packets wasting bandwidth.

virtual MStdString MStreamSocket::GetPeerSocketName ( ) const

virtual

Get the IP address for the peer socket.

The IP address returned has text representation, such as "10.0.0.120".

Precondition: Socket has to be initialized, and the connection is active, otherwise a system error is thrown.

Implements MStreamSocketBase.

virtual unsigned MStreamSocket::GetPeerSocketPort ( ) const

virtual

Get the port for the peer socket.

Precondition: Socket has to be initialized, and the connection is active, otherwise a system error is thrown.

Implements MStreamSocketBase.

int MStreamSocket::GetReceiveBufferSize ( ) const

Receive Buffer size socket option.

This controls how many bytes are allocated for the socket receive buffer.

Precondition: Socket has to be created.

int MStreamSocket::GetSendBufferSize ( ) const

Send Buffer size socket option.

This controls how many bytes are allocated for the socket send buffer.

Precondition: Socket has to be created.

unsigned MStreamSocket::GetSendTimeout ( ) const

inline

Socket send timeout in milliseconds, 60000 by default.

If a send call times out, the connection is in an indeterminate state and should be closed.

void MStreamSocket::Listen ( unsigned backlog = 5 )

Listen for incoming socket connections.

Usually, there is a special dedicated port to listen for incoming connections. When the connection comes, Accept has to be called with the new socket as parameter.

Parameters

backlog Length of the pending connections queue, by default it is 5 pending connections.

Precondition: The socket has to be created successfully, and bound to a port known by clients. Otherwise this is a programming error, and the socket-specific exception is called.

unsigned MStreamSocket::Recv	(	char *	buffer,
		unsigned	length,
		int	flags
	)

Analog of the standard socket function recv.

Receive a number of bytes currently available in the socket. This method is an alternative to stream Read methods, however in majority of cases Read methods are sufficient to manipulate the socket. They also have more functionality such as handling of encrypted or compressed streams.

Parameters

buffer	Buffer into which to receive the data.
length	Length of the buffer or how many bytes to read.
flags	Standard recv flags.

Returns: How many bytes are received into buffer.

Precondition: The connection is alive, otherwise the socket exception is raised. It is okay to read zero bytes.

unsigned MStreamSocket::Send	(	const char *	buffer,
		unsigned	length,
		int	flags
	)

Send the buffer through the socket, standard socket function send.

Send as many bytes as the current send buffer can fit. This method is an alternative to stream Write methods, however in majority of cases Write methods are sufficient to manipulate the socket. They also have more functionality such as handling of encrypted or compressed streams.

Parameters

buffer	Buffer, which shall be written to socket.
length	Length of the buffer to write.
flags	Standard send flags.

Returns: How many bytes are sent.

Precondition: The connection is alive, otherwise the connection-specific exception is thrown.

void MStreamSocket::SetLinger	(	bool	doLinger,
		int	lingerTime
	)

Set Linger socket option.

This controls how the socket behaves when the socket is closed. If doLinger is set to true and the data are present in the buffer, will delay closing the socket until the data are sent.

Parameters

doLinger	Whether to enable linger
lingerTime	For how long to linger. This has to be a positive value. When doLinger is true, and lingerTime is zero, RST is sent immediately at the close.

Precondition: Socket has to be created.

void MStreamSocket::SetNoDelay ( bool )

No Delay socket option.

Having No Delay true disables Nagle algorithm, which might cause an increase in network traffic, with smaller than needed packets wasting bandwidth.

void MStreamSocket::SetReceiveBufferSize ( int size )

Receive Buffer size socket option.

This controls how many bytes are allocated for the socket receive buffer.

Precondition: Socket has to be created.

void MStreamSocket::SetSendBufferSize ( int )

Send Buffer size socket option.

This controls how many bytes are allocated for the socket send buffer.

Precondition: Socket has to be created.

void MStreamSocket::SetSendTimeout ( unsigned milliseconds )

inline

Socket send timeout in milliseconds, 60000 by default.

If a send call times out, the connection is in an indeterminate state and should be closed.

void MStreamSocket::Swap ( MStreamSocket & other )

Swap this socket and the given socket by exchanging their handles and other properties.

After the successful completion, this socket and other socket will be exchanged.

bool MStreamSocket::TimedAccept	(	MStreamSocket &	socket,
		unsigned	timeout
	)

Accept the connection by the server and assign a new connection with the client, or timeout.

This method is typically called in the loop that also checks if the application shall cease waiting for the connection. For example, if it shall exit.

Parameters

socket	The uninitialized socket object to which the connection will be accepted.
timeout	Milliseconds to wait for the connection.

Returns

True means the connection is successfully accepted.
False means there is no connection, and timeout has expired.

See also: Accept method for infinite wait.

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation