Abstract IP socket, either TCP or UDP. More...

Inheritance diagram for MStreamSocketBase:

[legend]

Public Types

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...

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

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

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

virtual unsigned	GetPeerSocketPort () const =0
	Get the port for the peer 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...

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

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

virtual unsigned	GetBytesReadyToRead () const =0
	The number of bytes in the receive buffer that can be read immediately. 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...

virtual MStdString	GetName () const =0
	Return a representative name of a stream. 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...

Static Public Member Functions
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
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
	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

Abstract IP socket, either TCP or UDP.

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.

Member Typedef Documentation

typedef int MStreamSocketBase::SocketHandleType

Operating system dependent socket handle type.

Constructor & Destructor Documentation

MStreamSocketBase::MStreamSocketBase ( SocketHandleType socketHandle = InvalidSocket )

explicitprotected

Constructor that creates socket based on the existing socket handle.

Socket handles are only exposed to C++ interfaces. When a valid socket handle is given, the constructor applies sequence of actions that initialize stream object.

Parameters

socketHandle Handle to use by the socket. When handle is InvalidSocket, the stream opening sequence will not apply.

virtual MStreamSocketBase::~MStreamSocketBase ( )

protectedvirtual

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

static MByteString MStreamSocketBase::AddressToBinary ( const MStdString & addr )

static

Convert a string with IPv4 or IPv6 IP address into a binary form.

Parameters

addr	Either IPv4 or IPv6 address given in the string form. The type of the address is inferred by presence of a semicolon, which is the case of IPv6. The representation should be correct, otherwise an error is thrown.

Returns: The result binary representation, either four or sixteen bytes, depending on the address type given.

static MStdString MStreamSocketBase::BinaryToAddress ( const MByteString & addr )

static

Convert a binary form of IPv4 or IPv6 address into a string.

Parameters

addr	Either four or sixteen bytes for IPv4 or IPv6 address given as binary. The type of the address is inferred from the size, so any other sizes are rejected as incorrect.

Returns: The result string representation, either an IPv4 or IPv6.

void MStreamSocketBase::Bind	(	unsigned	port,
		const MStdString &	address = `MVariant::s_emptyString`
	)

Bind a server socket.

Parameters

port	The port to which to bind.
address	Address, such as "localhost". When not given, the bind is going to be made on all open interfaces.

virtual void MStreamSocketBase::ClearInputBuffer ( )

pure 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.

Implemented in MStreamSocket, and MStreamSocketUdp.

virtual unsigned MStreamSocketBase::GetBytesReadyToRead ( ) const

pure 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: WaitToReceive - Waits the specified time for the input data to arrive.

Implemented in MStreamSocket, and MStreamSocketUdp.

static MStdString MStreamSocketBase::GetLocalAddress ( )

static

Returns the host address for the local machine.

Precondition: The socket library is properly initialized and the local address exists. Otherwise an exception is thrown.

static MStdString MStreamSocketBase::GetLocalName ( )

static

Returns the standard host name for the local machine.

Precondition: The socket library is properly initialized and the local name exists with sockets. Otherwise an exception is thrown.

MStdString MStreamSocketBase::GetLocalSocketName ( ) const

Get the local name for this socket.

This is useful when connecting without binding as it provides a way to determine the local association, which has been set. This provides the access to the sockets call getsockname.

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

See also: GetLocalName - Static method to get the local host name.

unsigned MStreamSocketBase::GetLocalSocketPort ( ) const

Get the local port for a socket.

This is useful when connecting without binding as it provides a way to determine the local association which has been set. This provides the access to the sockets call getsockname.

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

virtual MStdString MStreamSocketBase::GetPeerSocketName ( ) const

pure 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.

Implemented in MStreamSocket, and MStreamSocketUdp.

virtual unsigned MStreamSocketBase::GetPeerSocketPort ( ) const

pure 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.

Implemented in MStreamSocket, and MStreamSocketUdp.

unsigned MStreamSocketBase::GetReceiveTimeout ( ) const

inline

Socket receive timeout in milliseconds, 60000 by default.

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

SocketHandleType MStreamSocketBase::GetSocketHandle ( ) const

inline

Socket handle for full operating system dependent control of the socket.

Caution shall be given when setting a handle as in this case the socket will not be open, and flags not set. Setting a handle is rather for replacing one open socket with another. No checks are done by either the getter or the setter of this property.

int MStreamSocketBase::GetSockOpt	(	int	level,
		int	option
	)

Get socket option as integer, access to the standard socket call.

This call is low level, OS dependent, and should be used with care.

Parameters

level	Defines the protocol level at which the option resides. Few often used values are defined in MSockOptEnum, while the complete set is available in OS dependent documentation for getsockopt
option	Socket option. Few often used values are defined in MSockOptEnum, while the complete set is available in OS dependent documentation for getsockopt

See also: MSockOptEnum - subset of possible values for level and option parameters; GetSockOptBytes - get those socket options that are not representable as integer; SetSockOpt - set socket option

MByteString MStreamSocketBase::GetSockOptBytes	(	int	level,
		int	option,
		unsigned	bufferSize
	)

Get socket option as byte string, access to the standard socket call.

This call is low level, OS dependent, and should be used with care.

Parameters

level	Defines the protocol level at which the option resides. Few often used values are defined in MSockOptEnum, while the complete set is available in OS dependent documentation for getsockopt
option	Socket option. Few often used values are defined in MSockOptEnum, while the complete set is available in OS dependent documentation for getsockopt
bufferSize	Returned buffer size

See also: MSockOptEnum - subset of possible values for level and option parameters; GetSockOpt - get integer socket options; SetSockOpt - set socket option

static bool MStreamSocketBase::IsAddressLocalIPv4 ( const MStdString & address )

static

True if the given string represents an IPv4 address.

Parameters

address String that represents an address.

Returns: true if the given string syntactically is an IPv4, false otherwise.

static bool MStreamSocketBase::IsAddressLocalIPv6 ( const MStdString & address )

static

True if the given string represents an IPv6 address.

Parameters

address String that represents an address.

Returns: true if the given string syntactically is an IPv6, false otherwise.

bool MStreamSocketBase::IsInputBufferEmpty ( ) const

Whether the input buffer has any data.

Returns true if there is no data in the input buffer, or false, if the data was received, and is ready to be read immediately.

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

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

void MStreamSocketBase::SetReceiveTimeout ( unsigned milliseconds )

inline

Socket receive timeout in milliseconds, 60000 by default.

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

void MStreamSocketBase::SetSocketHandle ( SocketHandleType )

Socket handle for full operating system dependent control of the socket.

Caution shall be given when setting a handle as in this case the socket will not be open, and flags not set. Setting a handle is rather for replacing one open socket with another. No checks are done by either the getter or the setter of this property.

void MStreamSocketBase::SetSockOpt	(	int	level,
		int	option,
		const MVariant &	value
	)

Set socket option, access to the standard socket call.

This call is low level, OS dependent, and should be used with care.

Parameters

level	Defines the protocol level at which the option resides. Few often used values are defined in MSockOptEnum, while the complete set is available in OS dependent documentation for getsockopt
option	Socket option. Few often used values are defined in MSockOptEnum, while the complete set is available in OS dependent documentation for getsockopt
value	Integer, byte, or byte string, value of the socket option

See also: MSockOptEnum - subset of possible values for level and option parameters; GetSockOpt - get integer socket options; GetSockOptBytes - get those socket options that are not representable as integer

bool MStreamSocketBase::WaitToReceive ( unsigned timeout = (unsigned) TimeoutInfinite ) const

Waits the time given in milliseconds for the input data to arrive.

Returns true if the data are available, or false if not.

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

See also: IsInputBufferEmpty - Does not wait, but returns the information immediately.

bool MStreamSocketBase::WaitToSend ( unsigned timeout = (unsigned) TimeoutInfinite ) const

Waits the time given in milliseconds for the output buffer to become not full.

Returns true if the data can be sent, or false if not.

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

Member Data Documentation

const unsigned MStreamSocketBase::TimeoutDefault = 60000

static

Default socket read timeout in milliseconds.

One minute by default.

const unsigned MStreamSocketBase::TimeoutInfinite = (unsigned)-1

static

Timeout that represents infinity.

Not entirely infinite, but certainly too big for a socket.

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation