Abstraction of all channel-level communication media. More...

Inheritance diagram for MChannel:

[legend]

Classes
class	ReadTimeoutSavior
	Temporarily overrides read timeout with a new value using scope rules. More...

class	UninterruptibleCommunication
	Uninterruptible communication C++ wrapper. More...

Public Types
enum	{ CANCEL_COMMUNICATION_CHECK_OPTIMUM_INTERVAL = 1000 }

Public Member Functions
virtual MChannel *	CreateClone () const
	Virtual copy constructor, creates the channel, which is a clone of current. More...

virtual	~MChannel ()
	The destructor is public, and virtual. More...

virtual void	Connect ()
	Initializes channel and establishes connection between the computer and the end device. More...

virtual void	WaitForNextIncomingConnection (bool reinitialize=true)
	When GetAutoAnswer true, wait for the incoming connection without disconnecting the channel. More...

virtual void	Disconnect ()=0
	Disconnect brings down the data link, hangs up the phone, powers down the probe, etc. More...

void	WriteBytes (const MByteString &buffer)
	Writes the data to the channel, and returns when the last byte has been sent by the software. More...

void	WriteByte (Muint8 b)
	Writes a byte to the channel, and returns when it has been sent. More...

void	WriteBuffer (const char *buf, unsigned len)
	Writes the data buffer to the channel, and returns when the last character has been sent by the software (but hardware might still need to do some work). More...

Muint8	ReadByte ()
	Read a single byte from the channel. More...

void	ReadBuffer (char *buf, unsigned numberToRead)
	Read an exact number of characters from the channel. More...

void	Unread (const MVariant &byteOrBytes)
	Return the given byte or bytes to the stream buffer so they get read at the next read operation. More...

void	UnreadBuffer (const char *buff, unsigned size)
	Return the given bytes to the stream buffer so they get read at the next read operation. More...

MByteString	ReadBytes (unsigned numberToRead)
	Read bytes directly from the communication channel. More...

MByteString	ReadBytesUntil (const MByteString &terminatingString)
	Read bytes from the channel until a specified sequence is read. More...

MByteString	ReadBytesUntilAnyByte (const char *finisher, unsigned finisherSize, unsigned headerSize, unsigned footerSize)
	Read bytes from the channel until a specified sequence is read. More...

MByteString	ReadAllBytes ()
	Read an arbitrary number of characters from the channel, as much as available. More...

void	ClearInputBuffer ()
	Immediately discards all the pending characters from the channel. More...

void	ClearInputUntilSilence (unsigned milliseconds)
	Keep reading and ignoring input until there is silence. More...

virtual void	FlushOutputBuffer (unsigned numberOfCharsInBuffer=UINT_MAX)=0
	Ensure that the characters from the output buffer are sent. More...

virtual bool	IsConnected () const =0
	Returns the current connection state of the channel. More...

virtual void	CheckIfConnected ()
	Throw an appropriate exception if the channel is not connected. More...

void	CheckIfConnectedConst () const
	Throw an appropriate exception if the channel is not connected, constant version. More...

unsigned	GetCountBytesSent () const
	Number of bytes sent through the channel since its creation or since the last ResetCounts(). More...

unsigned	GetCountBytesReceived () const
	The number of bytes received through the channel since creation or since the last ResetCounts(). More...

virtual MStdString	GetMediaIdentification () const =0
	Returns a string that uniquely identifies the media through which this channel is communicating. More...

void	ResetCounts ()
	Reset channel statistical data, so the counters become zeros. More...

virtual void	WriteToMonitor (const MStdString &message)
	Synchronously write a message to the monitor, if it is connected. More...

virtual void	CancelCommunication (bool callDisconnect=false)
	Request canceling of the communication. More...

void	EnterUninterruptibleCommunication (bool notify=true)
	Enter a communication sequence that shall not be be interrupted with CancelCommunication call. More...

void	LeaveUninterruptibleCommunication (bool notify=true)
	Leave a communication sequence that shall not be be interrupted with CancelCommunication call. More...

void	CheckIfOperationIsCancelled ()
	Check if the user has requested the termination of the communication, and whether the cancel operation lock is zero. More...

void	Sleep (unsigned milliseconds)
	Channel version of Sleep, a delay function that is aware of cancel communication event. More...

unsigned	ReadWithTimeout (char *buf, unsigned size, unsigned timeout)
	Read up to size bytes into buffer using the given timeout. More...


bool	GetAutoAnswer () const

void	SetAutoAnswer (bool isAutoAnswer)


unsigned	GetAutoAnswerTimeout () const

void	SetAutoAnswerTimeout (unsigned timeout)


void	SetMonitor (MMonitor::Pointer monitor)

MMonitor::Pointer	GetMonitor () const


SHOW_INTERNAL bool	GetEcho () const

void	SetEcho (bool echo)


bool	GetSendEchoBytesToMonitor () const

void	SetSendEchoBytesToMonitor (bool doSend)


unsigned	GetIntercharacterTimeout () const

void	SetIntercharacterTimeout (unsigned timeout)


unsigned	GetReadTimeout () const

void	SetReadTimeout (unsigned timeout)


unsigned	GetWriteTimeout () const

void	SetWriteTimeout (unsigned timeout)

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

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties in MCOM syntax. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of publicly available persistent properties in MCOM syntax. More...

MStdString	GetPersistentPropertyValues (bool onlyNondefaults=false, bool excludeSecurityRelated=false) const
	Get the string with the list of persistent property names and their values. More...

void	SetPersistentPropertyValues (const MStdString &values)
	Set the persistent properties for the object using the string with the following format: More...

void	SetPropertyValues (const MDictionary &values)
	Set the properties for the object using the property list object. More...

void	WritePropertiesToMonitor ()
	Write all non-default values of protocol properties into monitor. More...

MStdString	DoGetPersistentPropertyValues0 () const
	Get the string with the whole list of persistent property names and their values. More...

MStdString	DoGetPersistentPropertyValues1 (bool onlyNondefaults) const
	Get the string with the list of persistent property names and their values. More...

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

Protected Member Functions
	MChannel ()
	Construct the channel object from parent class. More...

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

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

Additional Inherited Members
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 MObject
static const MClass	s_class
	Class of MObject.

Detailed Description

Abstraction of all channel-level communication media.

Channels are intended to provide the mechanism for reading and writing byte streams with timeouts.

Member Enumeration Documentation

anonymous enum

Enumerator
CANCEL_COMMUNICATION_CHECK_OPTIMUM_INTERVAL	How often in milliseconds to check for the communication to cancel.

Constructor & Destructor Documentation

MChannel::MChannel ( )

protected

Construct the channel object from parent class.

The constructor is protected because the class is abstract.

virtual MChannel::~MChannel ( )

virtual

The destructor is public, and virtual.

MChannel objects should be deleted by their owner, MCOMFactory creates Channels, but does not destroy them.

Member Function Documentation

virtual void MChannel::CancelCommunication ( bool callDisconnect = false )

virtual

Request canceling of the communication.

This service is typically called from a separate thread. The child channels might try to do some additional processing to cancel the communication. Disconnect will be called only if the parameter of the function is true.

Reimplemented in MChannelModem.

virtual void MChannel::CheckIfConnected ( )

virtual

Throw an appropriate exception if the channel is not connected.

The exception can be different depending on whether the connection was not made previously, or if the connection was unexpectedly terminated.

Precondition: The channel is connected, or an exception is thrown.

Reimplemented in MChannelSocket, and MChannelModem.

void MChannel::CheckIfConnectedConst ( ) const

inline

Throw an appropriate exception if the channel is not connected, constant version.

The exception can be different depending on whether the connection was not made previously, or if the connection was unexpectedly terminated.

Precondition: The channel is connected, or an exception is thrown.

See also: CheckIfConnected - non-constant version of this method.

void MChannel::CheckIfOperationIsCancelled ( )

Check if the user has requested the termination of the communication, and whether the cancel operation lock is zero.

If both conditions are yes, throw an exception MEOperationCancelled.

void MChannel::ClearInputBuffer ( )

Immediately discards all the pending characters from the channel.

Just like Connect or Disconnect, ClearInputBuffer is synchronous and is not queued. It should be used carefully when mixed with MProtocol's Queue Methods, which are transmitted to the end device only when QCommit is called.

Precondition: The channel is open, otherwise the operation fails with an exception.

See also: ClearInputUntilSilence Keep reading and ignoring input until there is silence.

void MChannel::ClearInputUntilSilence ( unsigned milliseconds )

Keep reading and ignoring input until there is silence.

Useful when it is known that the party will be sending data that has to be ignored.

Parameters

milliseconds Time in milliseconds, for how long the party keeps silent for the method to return. Typically, this is equal to intercharacter timeout.

See also: ClearInputBuffer Removes all bytes that are already present in the input buffer.

virtual void MChannel::Connect ( )

virtual

Initializes channel and establishes connection between the computer and the end device.

The specific set of actions depends on the channel type:

For an optical probe, the serial port is opened.
For a modem, the port is opened, then the modem is connected by either dialing-in, or by waiting for the call-back.
For socket channel the outgoing socket is connected or an incoming connection is accepted, depending on channel parameters.

Once the connection is established (Connect successfully completed), no other application can connect to the end device using the same communication line. Use the Disconnect method to terminate the connection. Be sure to include Disconnect in error handling routines, to ensure the link is always terminated. Otherwise, other applications may not be able to connect to the end device.

After successful Connect, bytes can be read/written to the meter.

Precondition: IsConnected should be false before calling this method. Many OS, environment, and program related exceptions can be thrown by this method.

See also: Disconnect

Reimplemented in MChannelOpticalProbe, MChannelModem, MChannelSerialPort, MChannelSocketUdp, MChannelSocket, and MChannelSocketBase.

virtual MChannel* MChannel::CreateClone ( ) const

virtual

Virtual copy constructor, creates the channel, which is a clone of current.

All persistent properties get copied, all other properties have initial values. Channel will not be connected, etc.

Reimplemented from MCOMObject.

virtual void MChannel::Disconnect ( )

pure virtual

Disconnect brings down the data link, hangs up the phone, powers down the probe, etc.

After Disconnect, no communication is possible with the meter. Calling Disconnect when the MChannel is not Connect()ed has no effect, and Disconnect itself will always be successful.

For MChannelOpticalProbe, this method simply releases the communication port back to the operating System, sets IsConnected to False, and returns.
For MChannelModem, a hang up sequence is performed on the modem prior to releasing the communication port back to the operating system and setting IsConnected to False.

Disconnect never generates an error. This allows it to be successfully issued even if the channel is not connected. This behavior was implemented in order to simplify handling of situations where the channel holds some resources but IsConnected = FALSE. For example, the modem link is disconnected, but the communication port is open and waiting to reestablish the connection. In this case, IsConnected = FALSE, but the communication port is still being held by the channel. Issuing Disconnect in this case would result in releasing the communication port back to the Operating System. It is not possible to use IsConnected in this situation to determine whether or not to issue the Disconnect method, so the Disconnect method was designed to operate successfully regardless of whether the channel is connected or disconnected.

Use the Connect method to establish the connection between the computer and the end device. As long as the connection exists, no other application can connect to the end device using the same communication line. Use Disconnect to terminate the connection. Include Disconnect in error handling routines, otherwise, other applications may not be able to connect to the end device.

See also: Connect

Implemented in MChannelOpticalProbe, MChannelModem, MChannelSocket, MChannelSerialPort, and MChannelSocketBase.

void MChannel::EnterUninterruptibleCommunication ( bool notify = true )

Enter a communication sequence that shall not be be interrupted with CancelCommunication call.

There is also LeaveUninterruptibleCommunication that ends such sequence. The matching pairs of these calls can be stacked. In which case the interruption can happen only after leaving the very top LeaveUninterruptibleCommunication.

virtual void MChannel::FlushOutputBuffer ( unsigned numberOfCharsInBuffer = UINT_MAX )

pure virtual

Ensure that the characters from the output buffer are sent.

The parameter, if specified, should match the number of characters written into the serial port right before FlushOutputBuffer is called. If the parameter is missing, the biggest possible number of characters will be ensured to go away.

Precondition: The channel is open, otherwise the operation fails with an exception.

Implemented in MChannelSocketBase, and MChannelSerialPort.

bool MChannel::GetAutoAnswer ( ) const

inline

Whether the channel initiates the communication or waits for the incoming connection.

When Connect() is issued, the state of Auto Answer determines whether the channel initiates communication (Auto Answer = false), or waits for the incoming connection (Auto Answer = true). When Auto Answer mode is enabled (Auto Answer = true), at the attempt to issue Connect() the channel waits GetAutoAnswerTimeout seconds for the incoming connection. The connection attempt can take a long time to complete or time out. If the connection is queued with QConnect and committed asynchronously with QCommit(True), then the connection can be aborted with QAbort.

All channels support initiating or waiting for the connection, though the typical use is to initiate the connection.

Since: Available to all channels since MeteringSDK Version 5.0.0.980.; Available to MChannelModem and MChannelModemCallback since MeteringSDK Version 2.1.27.; Available to MChannelSocket and MChannelSocketCallback since MeteringSDK Version 4.0.15.

Default value:: False [0], unless otherwise noted.
MChannelModemCallback defaults to True [1].
MChannelSocketCallback defaults to True [1].
MChannelSocketUdpCallback defaults to True [1].

Possible values:

True [1] : The channel waits for incoming connection.
False [0] : The channel initiates the connection.

unsigned MChannel::GetAutoAnswerTimeout ( ) const

inline

Time in seconds to wait for the incoming connection.

The number of seconds that the channel listens in Connect() for an inbound call or connection. GetAutoAnswer must be True for this property to have any effect. This can be a very large value for applications that want to continuously listen, however the maximum possible value is determined by the number of milliseconds in a 32-bit value, therefore, when an attempt is made to set the timeout to a value bigger than 2,147,483 seconds, the result will be about 24 days.

A good idea for the application is to commit the connection asynchronously using MProtocol::QConnect() and MProtocol::QCommit(bool asynchronous = true). This allows the application to continue to do work while waiting for the incoming connection, and also allows the connection attempt to be aborted with MProtocol::QAbort().

Since: Available to all channels since MeteringSDK Version 5.0.0.980.; Available to MChannelModem and MChannelModemCallback since MeteringSDK Version 2.1.27.; Available to MChannelSocket and MChannelSocketCallback since MeteringSDK Version 4.0.15.

Default value:: 60 seconds

Possible values: 0 .. MAXINT seconds.: However, values larger than 2,147,483 seconds may result in unpredictable timeouts as the maximum time is determined by the number of milliseconds in a 32-bit value. Prior to MeteringSDK Version 6.4.0.4908, values larger than 2,147,483 seconds could result in a silent overflow and an unpredictable timeout period. For MeteringSDK Versions 6.4.0.4908 and later, values larger than 2,147,483 seconds will result in a timeout of 2,147,483 seconds (slightly more than 24 days).

unsigned MChannel::GetCountBytesReceived ( ) const

inline

The number of bytes received through the channel since creation or since the last ResetCounts().

The count is nullified when the connection is created.

Since: MeteringSDK Version 2.2.17.

Possible values: 0 .. MAXUINT

unsigned MChannel::GetCountBytesSent ( ) const

inline

Number of bytes sent through the channel since its creation or since the last ResetCounts().

This count starts from zero at channel creation, or at a call to ResetCounts(), and it gets incremented for each byte successfully sent.

Since: MeteringSDK Version 2.2.17.

Possible values: 0 .. MAXUINT

SHOW_INTERNAL bool MChannel::GetEcho ( ) const

inline

Echo mode, whether the bytes are echoed back, so they have to be read by the channel.

Indicates whether or not the end device echoes every character transmitted through the channel. For example, Echo needs to be enabled for current loop devices and two-wire RS-485 devices.

Since: MeteringSDK Version 3.0.5.

Default value:

True [1] - For MChannelCurrentLoop
False [0] - For all other channels

Possible values:

True [1] - The end device echoes bytes back through the channel.
False [0] - The end device does not echo bytes.

See also: GetSendEchoBytesToMonitor - whether or not to send the echoed bytes to monitor.

unsigned MChannel::GetIntercharacterTimeout ( ) const

inline

Timeout value in between receiving any two characters.

All channel types have intercharacter timeout property. Intercharacter timeout is only applicable to read operations that request more than one byte. The protocols impose their own restrictions on IntercharacterTimeout, and they control this value while communicating. Advanced users may want to control this property when working directly with the channel using the available read services.

When the value of this property is nonzero, it controls the maximum time to wait between receiving any two consecutive bytes before initiating a timeout condition. Also, when intercharacter timeout is nonzero, ReadTimeout property guards time to receive the first character in the sequence. This mode is often the case for serial communications, and the way all current protocols, except ANSI C12.22, behave.

When this property is zero, the way timeouts are handled by the channel is altered. In this mode, intercharacter timeout is not guarded, however the ReadTimeout property becomes responsible for receiving the whole sequence. This mode is often the case for TCP/IP communications, and is the way ANSI C12.22 behaves.

Since: MeteringSDK Version 2.1.27.

Default value:: 500 milliseconds

Possible values:: 0 - Special value that alters the way timeouts are handled, see description text. 1 .. MAXINT value of intercharacter timeout in milliseconds.

virtual MStdString MChannel::GetMediaIdentification ( ) const

pure virtual

Returns a string that uniquely identifies the media through which this channel is communicating.

It will typically consist of computer host name, channel type and unique channel parameters pertinent to that channel type. Examples of media identifications:

"myhost:SOCKET:10.65.67.169:1153" - Socket channel initiated from host myhost towards IP address 10.65.67.169 and port 1153.
"wincomp10x64:SERIAL:COM1" - Optical probe channel that uses serial port COM1 of host wincomp10x64.
"wincomp10x64:SERIAL:COM25" - Direct serial channel that uses serial port COM25.

Channel types in the media identification string are more generic than MeteringSDK channel type names. For instance, whether the channel is optical probe or a current loop, it will return SERIAL as its identification type.

Implemented in MChannelSerialPort, and MChannelSocketBase.

MMonitor::Pointer MChannel::GetMonitor ( ) const

inline

Monitor object bound to the channel object.

The MMonitor object allows messages to be sent to a listening monitor application and to save the messages in a binary file that can be viewed later by loading it into the monitor application. The monitor application does not have to be running in order for a client to send messages or capture the communications into a binary file.

Precondition: The monitor pointer must be valid, or NULL.

Possible values:

Any valid MMonitor.
Null pointer to discard the previously set monitor.

unsigned MChannel::GetReadTimeout ( ) const

inline

Read timeout, responsible for receiving either the first byte or the whole packet.

The protocols always control this value themselves, while the user will typically handle it only when using the channel services to read from the channel directly.

The meaning of read timeout depends on the value of IntercharacterTimeout property as follows:

When IntercharacterTimeout is nonzero, the read timeout is the maximum time to wait for receiving the first character in a sequence before initiating a timeout condition. In this case, the timeout applicable to all subsequent characters in the same packet is the value of IntercharacterTimeout.
When IntercharacterTimeout is zero, the read timeout is guarding time to receive the whole sequence of bytes requested.

Since: MeteringSDK Version 2.1.27.

Default value:: 1000 milliseconds

Possible values: 0 .. MAXINT, timeout in milliseconds.

bool MChannel::GetSendEchoBytesToMonitor ( ) const

inline

Whether to send echo bytes to the MMonitor object, applicable to channel types that support the Echo property.

Enable or disable sending the Echo characters to the MMonitor object. Typically, users do not want to see the Echo'ed characters in the communications log. However, for developers that need to debug communication problems, having the Echo'ed characters in the communications log can be helpful.

Since: MeteringSDK Version 3.2.23.

Default value:: False [0]

Possible values:

True [1] : Send the echo'ed characters to the MMonitor object. If Echo = false, there are no Echo'ed characters to send, and no error is thrown.
False [0] : Do not send the echo'ed characters.

See also: GetEcho - property to control the channel echo.

unsigned MChannel::GetWriteTimeout ( ) const

inline

The maximum time to wait for the successful transmission of a packet before initiating a timeout error.

The protocols always control this value themselves. The user will typically handle it only when using the channel services to write to the port directly.

Since: MeteringSDK Version 2.1.27.

Default value:: 2000 milliseconds

Possible values: 0 .. MAXINT, timeout in milliseconds.

virtual bool MChannel::IsConnected ( ) const

pure virtual

Returns the current connection state of the channel.

IsConnected reflects the assumption the communication component has about the channel state, it does not guarantee that the next action with the channel will be successful. Issue the Connect service to establish the connection and the Disconnect service to terminate the connection.

For MChannelOpticalProbe, IsConnected will simply indicate that the resources for the communication port have been acquired.
For MChannelModem, IsConnected indicates that the resources have been acquired and that the modem has also successfully connected to another modem.

Default value:: False

Possible values:

True - The connection has been established.
False - The connection has not been established.

Implemented in MChannelModem, MChannelSerialPort, and MChannelSocketBase.

void MChannel::LeaveUninterruptibleCommunication ( bool notify = true )

Leave a communication sequence that shall not be be interrupted with CancelCommunication call.

There is also EnterUninterruptibleCommunication that ends such sequence. The matching pairs of these calls can be stacked. In which case the interruption can happen only after leaving the very top LeaveUninterruptibleCommunication. The communication is uninterrupted at next interaction with the channel, not at the call of this function.

MByteString MChannel::ReadAllBytes ( )

Read an arbitrary number of characters from the channel, as much as available.

Note this service assumes that the channel has flow control that tells when the read is done.

Precondition: The channel is open, otherwise the operation fails with an exception. Timeout exception is thrown if no characters were read from the channel during read timeout.

void MChannel::ReadBuffer	(	char *	buf,
		unsigned	numberToRead
	)

Read an exact number of characters from the channel.

Precondition: The channel is open, otherwise the operation fails with an exception. The number of characters given as parameter are received within the timeout period. Otherwise the timeout exception is thrown.

Muint8 MChannel::ReadByte ( )

Read a single byte from the channel.

Precondition: The channel is open, otherwise the operation fails with an exception. The character is received within timeout period. Otherwise the timeout exception is thrown.

MByteString MChannel::ReadBytes ( unsigned numberToRead )

Read bytes directly from the communication channel.

Unusual variations of the protocol can be simulated by sending data to the meter using WriteBytes, then reading the meter's response with ReadBytes. Invalid packets or noise data can also be sent to the meter for test purposes.

Just like Connect or Disconnect, ReadBytes is synchronous and is not queued. It should be used carefully when mixed with the MProtocol's Queue Methods, which are transmitted to the end device only when QCommit is called.

Parameters

numberToRead Number of bytes to read.

Precondition: The channel is open, otherwise the operation fails with an exception.

See also: GetIntercharacterTimeout - the number of milliseconds to wait for the byte to arrive before throwing a timeout exception.

MByteString MChannel::ReadBytesUntil ( const MByteString & terminatingString )

Read bytes from the channel until a specified sequence is read.

Precondition: The channel is open, otherwise the operation fails with an exception.

See also: GetIntercharacterTimeout - the number of milliseconds to wait for the byte to arrive before throwing a timeout exception.

MByteString MChannel::ReadBytesUntilAnyByte	(	const char *	finisher,
		unsigned	finisherSize,
		unsigned	headerSize,
		unsigned	footerSize
	)

Read bytes from the channel until a specified sequence is read.

Precondition: The channel is open, otherwise the operation fails with an exception.

See also: GetIntercharacterTimeout - the number of milliseconds to wait for the byte to arrive before throwing a timeout exception.

unsigned MChannel::ReadWithTimeout	(	char *	buf,
		unsigned	size,
		unsigned	timeout
	)

Read up to size bytes into buffer using the given timeout.

This method does not use ReadTimeout property, but it will not throw a timeout exception.

void MChannel::ResetCounts ( )

inline

Reset channel statistical data, so the counters become zeros.

The list of channel properties that are reset follows:

See also: MProtocol::ResetCounts() - reset extra counts available in the protocol, and in the associated channel.

void MChannel::SetAutoAnswer ( bool isAutoAnswer )

inline

Whether the channel initiates the communication or waits for the incoming connection.

When Connect() is issued, the state of Auto Answer determines whether the channel initiates communication (Auto Answer = false), or waits for the incoming connection (Auto Answer = true). When Auto Answer mode is enabled (Auto Answer = true), at the attempt to issue Connect() the channel waits GetAutoAnswerTimeout seconds for the incoming connection. The connection attempt can take a long time to complete or time out. If the connection is queued with QConnect and committed asynchronously with QCommit(True), then the connection can be aborted with QAbort.

All channels support initiating or waiting for the connection, though the typical use is to initiate the connection.

Since: Available to all channels since MeteringSDK Version 5.0.0.980.; Available to MChannelModem and MChannelModemCallback since MeteringSDK Version 2.1.27.; Available to MChannelSocket and MChannelSocketCallback since MeteringSDK Version 4.0.15.

Default value:: False [0], unless otherwise noted.
MChannelModemCallback defaults to True [1].
MChannelSocketCallback defaults to True [1].
MChannelSocketUdpCallback defaults to True [1].

Possible values:

True [1] : The channel waits for incoming connection.
False [0] : The channel initiates the connection.

void MChannel::SetAutoAnswerTimeout ( unsigned timeout )

Time in seconds to wait for the incoming connection.

The number of seconds that the channel listens in Connect() for an inbound call or connection. GetAutoAnswer must be True for this property to have any effect. This can be a very large value for applications that want to continuously listen, however the maximum possible value is determined by the number of milliseconds in a 32-bit value, therefore, when an attempt is made to set the timeout to a value bigger than 2,147,483 seconds, the result will be about 24 days.

A good idea for the application is to commit the connection asynchronously using MProtocol::QConnect() and MProtocol::QCommit(bool asynchronous = true). This allows the application to continue to do work while waiting for the incoming connection, and also allows the connection attempt to be aborted with MProtocol::QAbort().

Since: Available to all channels since MeteringSDK Version 5.0.0.980.; Available to MChannelModem and MChannelModemCallback since MeteringSDK Version 2.1.27.; Available to MChannelSocket and MChannelSocketCallback since MeteringSDK Version 4.0.15.

Default value:: 60 seconds

Possible values: 0 .. MAXINT seconds.: However, values larger than 2,147,483 seconds may result in unpredictable timeouts as the maximum time is determined by the number of milliseconds in a 32-bit value. Prior to MeteringSDK Version 6.4.0.4908, values larger than 2,147,483 seconds could result in a silent overflow and an unpredictable timeout period. For MeteringSDK Versions 6.4.0.4908 and later, values larger than 2,147,483 seconds will result in a timeout of 2,147,483 seconds (slightly more than 24 days).

void MChannel::SetEcho ( bool echo )

inline

Echo mode, whether the bytes are echoed back, so they have to be read by the channel.

Indicates whether or not the end device echoes every character transmitted through the channel. For example, Echo needs to be enabled for current loop devices and two-wire RS-485 devices.

Since: MeteringSDK Version 3.0.5.

Default value:

True [1] - For MChannelCurrentLoop
False [0] - For all other channels

Possible values:

True [1] - The end device echoes bytes back through the channel.
False [0] - The end device does not echo bytes.

See also: GetSendEchoBytesToMonitor - whether or not to send the echoed bytes to monitor.

void MChannel::SetIntercharacterTimeout ( unsigned timeout )

Timeout value in between receiving any two characters.

All channel types have intercharacter timeout property. Intercharacter timeout is only applicable to read operations that request more than one byte. The protocols impose their own restrictions on IntercharacterTimeout, and they control this value while communicating. Advanced users may want to control this property when working directly with the channel using the available read services.

When the value of this property is nonzero, it controls the maximum time to wait between receiving any two consecutive bytes before initiating a timeout condition. Also, when intercharacter timeout is nonzero, ReadTimeout property guards time to receive the first character in the sequence. This mode is often the case for serial communications, and the way all current protocols, except ANSI C12.22, behave.

When this property is zero, the way timeouts are handled by the channel is altered. In this mode, intercharacter timeout is not guarded, however the ReadTimeout property becomes responsible for receiving the whole sequence. This mode is often the case for TCP/IP communications, and is the way ANSI C12.22 behaves.

Since: MeteringSDK Version 2.1.27.

Default value:: 500 milliseconds

Possible values:: 0 - Special value that alters the way timeouts are handled, see description text. 1 .. MAXINT value of intercharacter timeout in milliseconds.

void MChannel::SetMonitor ( MMonitor::Pointer monitor )

Monitor object bound to the channel object.

The MMonitor object allows messages to be sent to a listening monitor application and to save the messages in a binary file that can be viewed later by loading it into the monitor application. The monitor application does not have to be running in order for a client to send messages or capture the communications into a binary file.

Precondition: The monitor pointer must be valid, or NULL.

Possible values:

Any valid MMonitor.
Null pointer to discard the previously set monitor.

void MChannel::SetReadTimeout ( unsigned timeout )

Read timeout, responsible for receiving either the first byte or the whole packet.

The protocols always control this value themselves, while the user will typically handle it only when using the channel services to read from the channel directly.

The meaning of read timeout depends on the value of IntercharacterTimeout property as follows:

When IntercharacterTimeout is nonzero, the read timeout is the maximum time to wait for receiving the first character in a sequence before initiating a timeout condition. In this case, the timeout applicable to all subsequent characters in the same packet is the value of IntercharacterTimeout.
When IntercharacterTimeout is zero, the read timeout is guarding time to receive the whole sequence of bytes requested.

Since: MeteringSDK Version 2.1.27.

Default value:: 1000 milliseconds

Possible values: 0 .. MAXINT, timeout in milliseconds.

void MChannel::SetSendEchoBytesToMonitor ( bool doSend )

inline

Whether to send echo bytes to the MMonitor object, applicable to channel types that support the Echo property.

Enable or disable sending the Echo characters to the MMonitor object. Typically, users do not want to see the Echo'ed characters in the communications log. However, for developers that need to debug communication problems, having the Echo'ed characters in the communications log can be helpful.

Since: MeteringSDK Version 3.2.23.

Default value:: False [0]

Possible values:

True [1] : Send the echo'ed characters to the MMonitor object. If Echo = false, there are no Echo'ed characters to send, and no error is thrown.
False [0] : Do not send the echo'ed characters.

See also: GetEcho - property to control the channel echo.

void MChannel::SetWriteTimeout ( unsigned timeout )

The maximum time to wait for the successful transmission of a packet before initiating a timeout error.

The protocols always control this value themselves. The user will typically handle it only when using the channel services to write to the port directly.

Since: MeteringSDK Version 2.1.27.

Default value:: 2000 milliseconds

Possible values: 0 .. MAXINT, timeout in milliseconds.

void MChannel::Sleep ( unsigned milliseconds )

Channel version of Sleep, a delay function that is aware of cancel communication event.

Different from MUtilities.Sleep, this function might throw cancel communication exception.

void MChannel::Unread ( const MVariant & byteOrBytes )

Return the given byte or bytes to the stream buffer so they get read at the next read operation.

Precondition: The channel is open, otherwise the operation fails with an exception.

void MChannel::UnreadBuffer	(	const char *	buff,
		unsigned	size
	)

Return the given bytes to the stream buffer so they get read at the next read operation.

Precondition: The channel is open, otherwise the operation fails with an exception.

virtual void MChannel::WaitForNextIncomingConnection ( bool reinitialize = true )

virtual

When GetAutoAnswer true, wait for the incoming connection without disconnecting the channel.

A typical server application sequence that uses this call:

Connect() // wait for the first incoming connection
loop until interrupted:
    ... communicate ...
    WaitForNextIncomingConnection() // wait for the next incoming connection
end loop
Disconnect()

Parameters

reinitialize Tells if reinitialization of the channel has to be made at each new incoming connection.

Precondition: Prior to this call, the channel needs to be configured with SetAutoAnswer true, and the connection established with Connect(). Not all channels support Auto Answer mode, and might throw an exception. A timeout exception is thrown if no call is received during the GetAutoAnswerTimeout period.

Reimplemented in MChannelModem, MChannelSerialPort, MChannelSocketUdp, and MChannelSocket.

void MChannel::WriteBuffer	(	const char *	buf,
		unsigned	len
	)

Writes the data buffer to the channel, and returns when the last character has been sent by the software (but hardware might still need to do some work).

To ensure that all data is sent, use FlushOutputBuffer.

Precondition: The channel is open, otherwise the operation fails with an exception. The buffer is initialized correctly, otherwise the behavior is undefined.

void MChannel::WriteByte ( Muint8 b )

Writes a byte to the channel, and returns when it has been sent.

After the method returns the hardware might still need to do some work to actually send the buffer. To ensure that all data is sent, use FlushOutputBuffer.

Unusual variations of the protocol can be simulated by sending data to the meter using WriteBytes, then reading the meter's response with ReadBytes. Invalid packets or noise data can also be sent to the meter for test purposes.

Just like Connect or Disconnect, WriteBytes is synchronous and is not queued. It should be used carefully when mixed with MProtocol's Queue Methods, which are transmitted to the end device only when QCommit is called.

Precondition: The channel is open, otherwise the operation fails with an exception.

Parameters

b	Byte to write to the channel.

void MChannel::WriteBytes ( const MByteString & buffer )

Writes the data to the channel, and returns when the last byte has been sent by the software.

After the method returns the hardware might still need to do some work to actually send the buffer. To ensure that all data is sent, use FlushOutputBuffer.

Unusual variations of the protocol can be simulated by sending data to the meter using WriteBytes, then reading the meter's response with ReadBytes. Invalid packets or noise data can also be sent to the meter for test purposes.

Just like Connect or Disconnect, WriteBytes is synchronous and is not queued. It should be used carefully when mixed with MProtocol's Queue Methods, which are transmitted to the end device only when QCommit is called.

Precondition: The channel is open, otherwise the operation fails with an exception.

Parameters

buffer An array of bytes to pass to the channel. The byte in the lower bound of the array is the first byte to be transmitted and the byte in the upper bound of the array is the last byte to be transmitted.

virtual void MChannel::WriteToMonitor ( const MStdString & message )

virtual

Synchronously write a message to the monitor, if it is connected.

No errors are ever thrown by this method, if there is no monitor connected, nothing is done.

Reimplemented from MCOMObject.

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation