|
C12Adapter Opensource C++ Interface
|
Abstraction of a communication protocol. More...
Classes | |
| struct | TableRawData |
| Table raw data associated with the table number. More... | |
Public Types | |
| enum | { MAXIMUM_NUMBER_STRING_SIZE = 64, MAXIMUM_SERVICE_NAME_STRING_SIZE = MAXIMUM_NUMBER_STRING_SIZE + 64, DEFAULT_ESTIMATED_RESPONSE_SIZE = 0x1000, MAXIMUM_POSSIBLE_TABLE_OFFSET = 0xFFFFFF, MAXIMUM_POSSIBLE_TABLE_LENGTH = 0xFFFFFF } |
| typedef std::vector< TableRawData > | TableRawDataVector |
| Vector of table raw data. | |
Public Member Functions | |
| virtual MProtocol * | CreateClone () const |
| Virtual copy constructor, creates the protocol which is a clone of current. More... | |
| virtual | ~MProtocol ()=0 |
| Destroy the protocol object. More... | |
| void | Finalize () |
| Execute this method as first action in the destructor of any child protocol. More... | |
| unsigned | GetCountApplicationLayerServicesSuccessful () const |
| The number of Application Layer services that have been successfully processed. More... | |
| void | IncrementCountApplicationLayerServicesSuccessful () |
| Increment the number of application layer services successfully processed. More... | |
| unsigned | GetCountApplicationLayerServicesRetried () const |
| The number of Application Layer services that have been retried. More... | |
| void | IncrementCountApplicationLayerServicesRetried () |
| Increment the number of application layer services retried. More... | |
| unsigned | GetCountApplicationLayerServicesFailed () const |
| The number of Application Layer services that have failed. More... | |
| void | IncrementCountApplicationLayerServicesFailed () |
| Increment the number of application layer services failed. More... | |
| unsigned | GetCountLinkLayerPacketsSuccessful () const |
| The number of Link Layer packets that have been successfully processed. More... | |
| void | IncrementCountLinkLayerPacketsSuccessful () |
| Increment the number of data link layer packets successfully processed. More... | |
| unsigned | GetCountLinkLayerPacketsRetried () const |
| The number of Link Layer packets that have been retried. More... | |
| void | IncrementCountLinkLayerPacketsRetried () |
| Increment the number of data link layer packets retried. More... | |
| unsigned | GetCountLinkLayerPacketsFailed () const |
| Get number of data link layer packets failed. More... | |
| void | IncrementCountLinkLayerPacketsFailed () |
| Increment the number of data link layer packets failed. More... | |
| unsigned | GetMaximumRoundTripTime () const |
| Gets the maximum measured approximate packet round trip time over the link layer. More... | |
| unsigned | GetMinimumRoundTripTime () const |
| Gets the minimum measured approximate packet round trip time over the link layer. More... | |
| unsigned | GetAverageRoundTripTime () const |
| Gets the average measured approximate packet round trip time over the link layer. More... | |
| void | ClearPasswordList () |
| Set the password list for the protocol to none, so the SetPassword property is used. More... | |
| void | AddToPasswordList (const MByteString &password) |
| Add a password to the password list. More... | |
| int | GetPasswordListSuccessfulEntry () const |
| Return the entry, which was successfully tried with the meter. More... | |
| void | ResetCounts () |
| Clear the statistical data for the channel. More... | |
| virtual void | ApplyChannelParameters () |
| Setup the configuration of the channel in a way compatible with the protocol handshake sequence. More... | |
| void | Connect () |
| Initializes the channel and establishes the connection with the peer. More... | |
| void | Disconnect () |
| Severs the connection between the computer and the end device. More... | |
| bool | IsConnected () const |
| Tells whether the protocol is currently connected. More... | |
| bool | IsInSession () const |
| Whether the protocol is in session. More... | |
| MProgressAction * | CreateRootProgressAction () |
| Create root of the progress actions hierarchy. More... | |
| MProgressAction * | GetLocalProgressAction () |
| Read-only access to the currently preset local action in progress monitor. More... | |
| bool | QNeedToCommit () const |
| Whether or not it is time to call QCommit(true) in order to sync with the background thread. More... | |
| bool | QIsBackgroundCommunicationProgressing () const |
| True if the background communication is still progressing. More... | |
| bool | QIsDone () |
| Combines QNeedToCommit with the following QCommit in case all commands in the queue have been sent. More... | |
| void | QAbort () |
| Clears the commands in the queue, or cancel the ongoing background communication. More... | |
| void | QWriteToMonitor (const MStdString &message) |
| Add the message to write to the Monitor log file to MProtocol's command queue. More... | |
| void | QConnect () |
| Places a Connect command in the queue. More... | |
| void | QDisconnect () |
| Places a Disconnect command in the queue. More... | |
| void | QIdentifyMeter () |
| Places an IdentifyMeter task in the queue. More... | |
| void | QStartSession () |
| Adds a start session command to MProtocol's command queue. More... | |
| void | QEndSession () |
| Adds an end session command to MProtocol's command queue. More... | |
| void | QEndSessionNoThrow () |
| EndSessionNoThrow request is queued. More... | |
| void | QTableRead (MCOMNumberConstRef number, unsigned expectedSize, int id) |
| Adds a ReadTable command to MProtocol's command queue. More... | |
| void | QTableWrite (MCOMNumberConstRef number, const MByteString &data) |
| Adds a table write command to MProtocol's command queue. More... | |
| void | QTableReadPartial (MCOMNumberConstRef number, int offset, int size, int id) |
| Adds a partial table read command to MProtocol's command queue. More... | |
| void | QTableWritePartial (MCOMNumberConstRef number, const MByteString &data, int offset) |
| Adds a partial table write command to MProtocol's command queue. More... | |
| void | QFunctionExecute (MCOMNumberConstRef number) |
| Place a function without data request in MProtocol command queue. More... | |
| void | QFunctionExecuteRequest (MCOMNumberConstRef number, const MByteString &request) |
| Place a function with request data in MProtocol's command queue. More... | |
| void | QFunctionExecuteResponse (MCOMNumberConstRef number, int id, unsigned estimatedResponseSize=DEFAULT_ESTIMATED_RESPONSE_SIZE) |
| Place a function with response data in MProtocol's command queue. More... | |
| void | QFunctionExecuteRequestResponse (MCOMNumberConstRef number, const MByteString &request, int id, unsigned estimatedResponseSize=DEFAULT_ESTIMATED_RESPONSE_SIZE) |
| Place a function with request and response data in MProtocol's command queue. More... | |
| virtual void | QCommit (bool asynchronously=false) |
| Executes all operations in MProtocol's command queue. More... | |
| MByteString | QGetTableData (MCOMNumberConstRef number, int id=-1) |
| Fetch the table data after the table read has been successfully performed by QCommit. More... | |
| MByteString | QGetFunctionData (MCOMNumberConstRef number, int id=-1) |
| Fetch the function response data after the function has been successfully executed in QCommit. More... | |
| MStdString | QGetIdentifyMeterData () |
| Fetch the identify meter string after the QIdentifyMeter has been successfully performed in QCommit. More... | |
| virtual void | WriteToMonitor (const MStdString &message) |
| Synchronously write a message to the monitor, if it is connected. More... | |
| void | WriteCountsToMonitor () |
| Write running values of communication quality counters to monitor. More... | |
| void | StartSession () |
| Synchronously start the session. More... | |
| void | EndSession () |
| Synchronously end the session. More... | |
| void | EndSessionNoThrow () |
| End the session, but do not throw errors. More... | |
| Muint8 | ReadStartByte (const MByteString &setOfValidStartBytes, unsigned trafficTimeout) |
| Read the start byte of the packet in a proper way, taking into consideration timeouts and ignoring garbage. More... | |
| MByteString | TableRead (MCOMNumberConstRef number, unsigned expectedSize=0) |
| Synchronously read the whole table with number given as parameter. More... | |
| void | TableReadBuffer (MCOMNumberConstRef number, void *buff, unsigned size) |
| Same as ReadTable, but instead of returning a byte string, read table into a given buffer. More... | |
| template<class T > | |
| void | TableReadBuffer (MCOMNumberConstRef number, T &table) |
| Same as ReadTable, but instead of returning a byte string, read table into a given template variable. More... | |
| MByteString | TableReadNoThrow (MCOMNumberConstRef number, MException **exception, unsigned expectedSize=0) |
| Synchronously read the whole table with number given as parameter, do not throw an exception, but rather return it. More... | |
| void | TableWrite (MCOMNumberConstRef number, const MByteString &data) |
| Synchronously write the whole table with number given as parameter. More... | |
| void | TableWriteBuffer (MCOMNumberConstRef number, const void *data, unsigned size) |
| Same as TableWrite, but uses buffer, given as data and size parameters. More... | |
| template<class T > | |
| void | TableWriteBuffer (MCOMNumberConstRef number, const T &table) |
| Same as WriteTable, but uses variable of some specific template class or structure. More... | |
| MByteString | TableReadPartial (MCOMNumberConstRef number, int offset, int size) |
| Synchronously read part of the table with number given as parameter. More... | |
| void | TableReadPartialBuffer (MCOMNumberConstRef number, int offset, void *buff, unsigned size) |
| Same as TableReadPartial, but instead of returning a byte string, read table into a given buffer. More... | |
| template<class T > | |
| void | TableReadPartialBuffer (MCOMNumberConstRef number, T &table, int offset) |
| Same as TableReadPartial, but instead of returning a byte string, partially read table into a given template variable. More... | |
| void | TableWritePartial (MCOMNumberConstRef number, const MByteString &data, int offset) |
| Synchronously write part of the table with number given as parameter. More... | |
| void | TableWritePartialBuffer (MCOMNumberConstRef number, int offset, const void *buff, unsigned size) |
| Same as TableWritePartial, but instead of using a byte string, write table using a given buffer. More... | |
| template<class T > | |
| void | TableWritePartialBuffer (MCOMNumberConstRef number, const T &table, int offset) |
| Same as TableWritePartial, but instead of using a byte string, write table using a given template class contents. More... | |
| void | FunctionExecute (MCOMNumberConstRef number) |
| Synchronously execute the function with no parameters, the number of the function is given as parameter. More... | |
| void | FunctionExecuteRequest (MCOMNumberConstRef number, const MByteString &request) |
| Synchronously execute the function with request data, the number of the function is given as parameter. More... | |
| MByteString | FunctionExecuteResponse (MCOMNumberConstRef number) |
| Synchronously execute the function with response data, the number of the function is given as parameter. More... | |
| MByteString | FunctionExecuteRequestResponse (MCOMNumberConstRef number, const MByteString &request) |
| Synchronously execute the function with request and response data, the number of the function is given as parameter. More... | |
| virtual unsigned | GetNumberOfDataLinkPackets (MCommunicationCommand::CommandType typeOfRequest, unsigned applicationLayerDataSize=0) |
| Return the number of data link packets that are required for a given request, provided an optional size of the application data. More... | |
| MStdString | IdentifyMeterWithContext (bool sessionIsStarted=false, TableRawDataVector *tablesRead=NULL) |
| Identify the meter if the protocol is known (note this is not an ANSI Identify protocol command). More... | |
| virtual unsigned | CalculateChecksumFromBuffer (const char *buff, unsigned size) const |
| Protocol dependent one-byte checksum calculation procedure that uses buffer and its size. More... | |
| unsigned | CalculateChecksum (const MByteString &buffer) const |
| Protocol dependent one-byte checksum calculation procedure that uses byte string. More... | |
| virtual Muint16 | CalculateCRC16FromBuffer (const char *buff, unsigned size) const |
| Abstract protocol dependent two-byte CRC calculation procedure, takes buffer chunk with the size. More... | |
| unsigned | CalculateCRC16 (const MByteString &buffer) const |
| Protocol dependent two-byte CRC calculation procedure that accepts the byte string. More... | |
| void | Sleep (unsigned milliseconds) |
| Calls channel's Sleep method if the channel is present. More... | |
| bool | GetMeterIsLittleEndian () const |
| void | SetMeterIsLittleEndian (bool isLittleEndian) |
| MChannel * | GetChannel () const |
| void | SetChannel (MChannel *channel) |
| bool | IsChannelOwned () const |
| void | SetIsChannelOwned (bool yes) |
| bool | GetKeepSessionAlive () const |
| void | SetKeepSessionAlive (bool alive) |
| MByteString | GetPassword () const |
| void | SetPassword (const MByteString &password) |
| const MByteStringVector & | GetPasswordList () const |
| void | SetPasswordList (const MByteStringVector &passwordList) |
| MProgressMonitor * | GetProgressMonitor () const |
| void | SetProgressMonitor (MProgressMonitor *p) |
| MCommunicationQueue & | GetCommandQueue () |
| M_NO_PROGRESS_MONITOR. More... | |
| const MCommunicationQueue & | GetCommandQueue () const |
| M_NO_PROGRESS_MONITOR. More... | |
| MStdString | IdentifyMeter (bool sessionIsStarted=false) |
| MStdString | DoIdentifyMeter0 () |
 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 ¶ms) |
| 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 ¶ms) |
| 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... | |
Static Public Member Functions | |
| static unsigned | StaticCalculateChecksumFromBuffer (const char *buff, unsigned size) |
| Most popular one-byte checksum calculation procedure, a sum of all bytes. More... | |
| static unsigned | StaticCalculateChecksum (const MByteString &buffer) |
| Compute checksum of the byte string given as parameters. 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... | |
Protected Member Functions | |
| MProtocol (MChannel *channel, bool channelIsOwned=true) | |
| Create a new abstract protocol with the channel given. More... | |
| virtual void | DoStartSession () |
| Synchronously start the session, don't do service count. More... | |
| virtual void | DoEndSession () |
| Synchronously end the session, don't do service count. More... | |
| virtual void | DoTableRead (MCOMNumberConstRef number, MByteString &data, unsigned expectedSize=0) |
| Synchronously read the whole table with number given as parameter, don't do service count. More... | |
| virtual void | DoTableWrite (MCOMNumberConstRef number, const MByteString &data) |
| Synchronously write the whole table with number given as parameter, don't do service count. More... | |
| virtual void | DoTableReadPartial (MCOMNumberConstRef number, MByteString &data, int offset, int size) |
| Synchronously read part of the table with number given as parameter, don't do service count. More... | |
| virtual void | DoTableWritePartial (MCOMNumberConstRef number, const MByteString &data, int offset) |
| Synchronously write part of the table with number given as parameter, don't do service count. More... | |
| virtual void | DoFunctionExecute (MCOMNumberConstRef number) |
| Synchronously execute the function with no parameters, the number of the function is given as parameter, don't do service count. More... | |
| virtual void | DoFunctionExecuteRequest (MCOMNumberConstRef number, const MByteString &request) |
| Synchronously execute the function with request data, the number of the function is given as parameter, don't do service count. More... | |
| virtual void | DoFunctionExecuteResponse (MCOMNumberConstRef number, MByteString &response) |
| Synchronously execute the function with response data, the number of the function is given as parameter, don't do service count. More... | |
| virtual void | DoFunctionExecuteRequestResponse (MCOMNumberConstRef number, const MByteString &request, MByteString &response) |
| Synchronously execute the function with request and response data, the number of the function is given as parameter, don't do service count. More... | |
| virtual MStdString | DoIdentifyMeter (bool sessionIsStarted, TableRawDataVector *tablesRead) |
| Identify the meter if the protocol is known (note this is not an ANSI Identify protocol command). More... | |
| void | DoTryPasswordOrPasswordList () |
| Try password or passwords for the protocol according to the PASSWORD and PasswordList settings. More... | |
| virtual void | DoTryPasswordEntry (const MByteString &entry) |
| Try one password, throw if error. More... | |
| virtual void | DoBuildComplexServiceName (MChars fullServiceName, MConstChars serviceName, MCOMNumberConstRef number, int par1=-1, int par2=-1) |
| Build service name with a number and given parameters. More... | |
| void | DoBuildPossiblyNumericComplexServiceName (MChars fullServiceName, MConstChars serviceName, MCOMNumberConstRef number, bool isHex, int par1=-1, int par2=-1) |
| Helper service name builder that can interpret numeric values either as hex or as decimal. 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 Attributes inherited from MObject | |
| static const MClass | s_class |
| Class of MObject. | |
Abstraction of a communication protocol.
The protocol is able to execute application level commands directly, or through the command queue interface. The concrete instances of protocol will implement the abstractions defined by this class, plus some extra services and attributes specific to those protocols.
Preferred way of creating a protocol is through MCOMFactory, and typically, the protocol will be created together with MChannel object using MCOMFactory::CreateProtocol()
| anonymous enum |
|
protected |
Create a new abstract protocol with the channel given.
The service is protected because the class is abstract.
| channel | Channel object of the protocol. It will be a rare case when a protocol can be created without a channel, in which case this parameter can be NULL. |
| channelIsOwned | Whether the channel has to be owned by the protocol, deleted in protocol destructor or at channel reassignment. By default the protocol owns its channel. |
|
pure virtual |
Destroy the protocol object.
If the channel is owned, IsChannelOwned is true, the channel is also destroyed.
| void MProtocol::AddToPasswordList | ( | const MByteString & | password | ) |
Add a password to the password list.
| password | Shall be valid for this protocol, or an error is thrown. |
|
virtual |
Setup the configuration of the channel in a way compatible with the protocol handshake sequence.
The action depends on the channel and protocol. Implementations ensure that the service behaves gracefully no matter whether the channel is connected or not.
Reimplemented in MProtocolC1222, MProtocolC12, MProtocolC1218, and MProtocolC1221.
| unsigned MProtocol::CalculateChecksum | ( | const MByteString & | buffer | ) | const |
Protocol dependent one-byte checksum calculation procedure that uses byte string.
This implementation uses a protocol-dependent virtual call.
| buffer | Buffer for which to calculate one-byte checksum. |
|
virtual |
Protocol dependent one-byte checksum calculation procedure that uses buffer and its size.
This particular implementation of the checksum calculation fits the majority of the protocols, override if needed.
| buff | The pointer to the buffer for which to calculate the checksum. |
| size | Size of the buffer. |
Reimplemented in MProtocolC12.
|
inline |
Protocol dependent two-byte CRC calculation procedure that accepts the byte string.
This implementation uses a protocol-dependent virtual call.
| buffer | The buffer for which to calculate CRC16. |
|
virtual |
Abstract protocol dependent two-byte CRC calculation procedure, takes buffer chunk with the size.
| buff | The pointer to the buffer for which to calculate CRC16. |
| size | Size of the buffer. |
Reimplemented in MProtocolC12.
| void MProtocol::ClearPasswordList | ( | ) |
Set the password list for the protocol to none, so the SetPassword property is used.
When the password list is not clear, property SetPassword will not apply.
| void MProtocol::Connect | ( | ) |
Initializes the channel and establishes the connection with the peer.
Prior to calling MChannel::Connect(), this protocol method does extra checks, and calls ApplyChannelParameters(). Unless MChannel is used without MProtocol, it is recommended to use protocol's Connect() method.
|
virtual |
Virtual copy constructor, creates the protocol which is a clone of current.
All persistent properties get copied, all other properties have initial values. If channel is owned, channel is duplicated. If channel is not owned, it is made shared.
Reimplemented from MCOMObject.
| MProgressAction* MProtocol::CreateRootProgressAction | ( | ) |
Create root of the progress actions hierarchy.
Any existing hierarchy is destroyed. If progress monitor is not set, dummy action is returned. A dummy action implements all action's properties and services as no-ops
| void MProtocol::Disconnect | ( | ) |
Severs the connection between the computer and the end device.
Unless MChannel is used without MProtocol, it is recommended to use protocol's Disconnect method.
Include Disconnect in error handling routines, otherwise, other applications may not be able to connect to the end device.
|
protectedvirtual |
Build service name with a number and given parameters.
If parameters are not present they are not in the name. The particular protocols can fill in their own implementations for full service name.
|
protected |
Helper service name builder that can interpret numeric values either as hex or as decimal.
If parameters are not present they are not in the name. The particular protocols can fill in their own implementations for full service name.
|
protectedvirtual |
Synchronously end the session, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol. Depending on the particular protocol this leads to sequence of logoff and terminate commands.
See EndSession, which is public. That one does necessary statistics, monitor handling and error message formatting.
Reimplemented in MProtocolC1218.
|
protectedvirtual |
Synchronously execute the function with no parameters, the number of the function is given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See FunctionExecute, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Synchronously execute the function with request data, the number of the function is given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See FunctionExecuteRequest, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Synchronously execute the function with request and response data, the number of the function is given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See FunctionExecuteRequestResponse, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Synchronously execute the function with response data, the number of the function is given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See FunctionExecuteResponse, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Identify the meter if the protocol is known (note this is not an ANSI Identify protocol command).
This protected service is indeed the one, which needs overwriting by a particular protocol.
If the first parameter is true, the service assumes the session is open, and it will not start the session, or close it. The second parameter, if it is not NULL, is filled with the data from tables, which DoIdentifyMeter had to read from the meter during its attempts to fetch the necessary information from the meter. This table vector can be used in order to minimize the communication with the meter, if this task has its place.
See IdentifyMeter, which is public. That one does necessary statistics, monitor handling and error message formatting.
| MStdString MProtocol::DoIdentifyMeter0 | ( | ) |
Identify the meter version and other information if the protocol is known.
Note that this is not an ANSI Identify protocol command. Typically, IdentifyMeter would be used when creating a meter of a known type, but an unknown version.
The IdentifyMeter service wraps the start and end session around the identification task. To call IdentifyMeter, one has to connect to the meter, but the session should not be started. This differs from QIdentifyMeter which does NOT wrap start and end session around the identification task.
Typically, IdentifyMeter returns only one identify string that identifies the meter. However, identify strings can be created for the option boards installed on a meter. In this case, the returned string can contain multiple identify strings, where the the meter's identify string is listed first and identify strings are separated by a semi- colon. Use GetIdentifyStrings to separate multiple identify strings.
The identify string is formatted as a J command and may not be suitable for showing to the user as it can contain non-printable characters. Instead, it is formatted for easy processing by a script or a program. A typical identify string returned for an A3 meter with LANOB option board follows (wrapped for clarity):
Example of A3 Identify string followed by LANOB's identify string, spaces and new lines used for clarity:
|
protectedvirtual |
Synchronously start the session, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol. Depending on the particular protocol this leads to sequence of handshake and logon commands.
See StartSession, which is public. That one does necessary statistics, monitor handling and error message formatting.
Reimplemented in MProtocolC1218, and MProtocolC1221.
|
protectedvirtual |
Synchronously read the whole table with number given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See TableRead, which is public. That one does necessary statistics, monitor handling and error message formatting.
The third argument is introduced to handle a special case where the table size is bigger than what the protocol allows, such as configuring an ANSI meter to have more load profile data than the 64K that can be transmitted with ANSI C12.18. In this case the table is read with multiple partial reads, where each partial read is sized to fit within the protocol constraints.
|
protectedvirtual |
Synchronously read part of the table with number given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See TableReadPartial, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Synchronously write the whole table with number given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See TableWrite, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Synchronously write part of the table with number given as parameter, don't do service count.
This protected service is indeed the one, which needs overwriting by a particular protocol.
See TableWritePartial, which is public. That one does necessary statistics, monitor handling and error message formatting.
|
protectedvirtual |
Try one password, throw if error.
This service has to be overloaded by every final protocol to attempt applying a given password.
|
protected |
Try password or passwords for the protocol according to the PASSWORD and PasswordList settings.
In case the password list is specified, only the password list is tried, if there is no password list, PASSWORD property is used.
| void MProtocol::EndSession | ( | ) |
Synchronously end the session.
Depending on the particular protocol this leads to sequence of logoff and terminate commands.
See QEndSession for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| void MProtocol::EndSessionNoThrow | ( | ) |
End the session, but do not throw errors.
| void MProtocol::Finalize | ( | ) |
Execute this method as first action in the destructor of any child protocol.
It is okay to call this method many times from a hierarchy of destructors, however nothing else shall be called after.
| void MProtocol::FunctionExecute | ( | MCOMNumberConstRef | number | ) |
Synchronously execute the function with no parameters, the number of the function is given as parameter.
See QFunctionExecute for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Function number |
| void MProtocol::FunctionExecuteRequest | ( | MCOMNumberConstRef | number, |
| const MByteString & | request | ||
| ) |
Synchronously execute the function with request data, the number of the function is given as parameter.
See QFunctionExecuteRequest for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Function number. |
| request | Request data. |
| MByteString MProtocol::FunctionExecuteRequestResponse | ( | MCOMNumberConstRef | number, |
| const MByteString & | request | ||
| ) |
Synchronously execute the function with request and response data, the number of the function is given as parameter.
See QFunctionExecuteRequestResponse for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Function number. |
| request | Request data. |
| MByteString MProtocol::FunctionExecuteResponse | ( | MCOMNumberConstRef | number | ) |
Synchronously execute the function with response data, the number of the function is given as parameter.
See QFunctionExecuteResponse for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Function number. |
|
inline |
Gets the average measured approximate packet round trip time over the link layer.
A 'round trip' is defined as the amount of time elapsed from the last byte sent to the first byte received back. Each trip is monitored, and the following properties updated accordingly: GetMinimumRoundTripTime, GetMaximumRoundTripTime, and GetAverageRoundTripTime.
The round trip times are not updated when there is a timeout, even if there were garbage characters on the line. The round trip times are nullified when the connection is created or when ResetCounts is issued.
|
inline |
Channel associated with this protocol.
When the channel is owned, and a new one is reassigned to the protocol, the previous channel will be deleted.
|
inline |
M_NO_PROGRESS_MONITOR.
Get the command queue of the protocol.
If the items were added to the queue by Q services, and no QCommit is performed yet, the queue is not empty.
|
inline |
M_NO_PROGRESS_MONITOR.
Get the command queue of the protocol.
If the items were added to the queue by Q services, and no QCommit is performed yet, the queue is not empty.
|
inline |
The number of Application Layer services that have failed.
The count is nullified when the connection is created, or when ResetCounts is issued.
|
inline |
The number of Application Layer services that have been retried.
The count is nullified when the connection is created, or when ResetCounts is issued. For some protocols the application layer retries never take place, in which case this property will remain at zero.
|
inline |
The number of Application Layer services that have been successfully processed.
The count is nullified when the protocol is created, and when ResetCounts is called.
|
inline |
Get number of data link layer packets failed.
The count is nullified when the connection is created, or when ResetCounts is issued. Some protocols, such as MProtocolC1222, do not have a link layer, therefore, they will not increment this counter.
|
inline |
The number of Link Layer packets that have been retried.
The count is nullified when the connection is created, or when ResetCounts is issued. Some protocols, such as MProtocolC1222, do not have a link layer, therefore, they will not increment this counter.
|
inline |
The number of Link Layer packets that have been successfully processed.
The count is nullified when the connection is created, or when ResetCounts is issued. Some protocols, such as MProtocolC1222, do not have a link layer, therefore, they will not increment this counter.
| bool MProtocol::GetKeepSessionAlive | ( | ) | const |
Whether the protocol should keep session alive in case of long inactivity.
When KeepSessionAlive is true, the session is kept from timing out. The feature can also be used to prevent an idling connection from being closed. What is done to keep the session alive is protocol dependent, but usually involves repeatedly sending some type of communication request to the meter. For some sessionless protocols this property has no effect.
The session is being kept alive by a background thread that is watching for the current value of property IsInSession. When IsInSession is true, the background communication is performed. Errors raised on the background can be silenced if IsConnected value was false. Otherwise, the session keeping errors will be thrown to the foreground thread at the next communication event, such as QCommit. Another place that checks and throws an error collected by the background thread is the assignment to KeepSessionAlive property itself. Therefore, the following will check for an error, and throw it if it was present:
When KeepSessionAlive is false, the session will time out or the connection will be closed according to the protocol rules.
| MProgressAction* MProtocol::GetLocalProgressAction | ( | ) |
Read-only access to the currently preset local action in progress monitor.
If progress monitor is not set, or if it does not have local action, dummy action is returned.
|
inline |
Gets the maximum measured approximate packet round trip time over the link layer.
A 'round trip' is defined as the amount of time elapsed from the last byte sent to the first byte received back. Each trip is monitored, and the following properties updated accordingly: GetMinimumRoundTripTime, GetMaximumRoundTripTime, and GetAverageRoundTripTime.
The round trip times are not updated when there is a timeout, even if there were garbage characters on the line. The round trip times are nullified when the connection is created or when ResetCounts is issued.
|
inline |
Primary data order of the device, whether it is little endian.
This information is used by some protocol implementations, for example, for ANSI procedures/functions implementation. Such protocols have application-level fields that depend on the protocol byte order.
It is only necessary to set this property when communicating to a device of different endianity as the protocol default. When communicating through the upper library levels this property can be set automatically.
|
inline |
Gets the minimum measured approximate packet round trip time over the link layer.
A 'round trip' is defined as the amount of time elapsed from the last byte sent to the first byte received back. Each trip is monitored, and the following properties updated accordingly: GetMinimumRoundTripTime, GetMaximumRoundTripTime, and GetAverageRoundTripTime.
The round trip times are not updated when there is a timeout, even if there were garbage characters on the line. The round trip times are nullified when the connection is created or when ResetCounts is issued.
|
virtual |
Return the number of data link packets that are required for a given request, provided an optional size of the application data.
Like for table read, this will be the expected size of the table to read, and for the table write this is the size of the table to be written. For function execution this is the sum of request and response sizes.
| typeOfRequest | The type of the request, the value within the enumeration range. There is a debug check for the value. |
| applicationLayerDataSize | Table size or the sum of function request and response size, whatever comprises the application layer of the given command. |
| MByteString MProtocol::GetPassword | ( | ) | const |
Application level password of the protocol.
The Password property is the binary value that is used to gain access to the device. No interpretation of C escape character sequences is performed on this string.
Many protocols will typically use password in the StartSession sequence, while some, such as sessionless mode of MProtocolC1222, will send password at every request.
The password can have less characters than the maximum number of characters allowed. In this case, during the communication, the password will be padded with a fill character (different for each protocol). For example, if an 8 character password is set to "1111", then the password "1111 " is transmitted during communications, while Password property will continue to report "1111". The padded characters are significant, and the password stored in the meter must exactly match the password used during communications (including the fill characters) or an error is generated.
|
inline |
Password list for the protocol.
The password lists, when not empty, overwrite the SetPassword property. In such case, passwords from the password list are applied in the ascending order until a successful entry is found. If none exists, the last error received during list processing is thrown.
| int MProtocol::GetPasswordListSuccessfulEntry | ( | ) | const |
Return the entry, which was successfully tried with the meter.
If there was no attempt to try the password list, or when none of the entries were successful, this property will be equal to -1.
|
inline |
Access to the progress monitor, if exists
| MStdString MProtocol::IdentifyMeter | ( | bool | sessionIsStarted = false | ) |
Identify the meter version and other information if the protocol is known.
Note that this is not an ANSI Identify protocol command. Typically, IdentifyMeter would be used when creating a meter of a known type, but an unknown version.
The IdentifyMeter service wraps the start and end session around the identification task. To call IdentifyMeter, one has to connect to the meter, but the session should not be started. This differs from QIdentifyMeter which does NOT wrap start and end session around the identification task.
Typically, IdentifyMeter returns only one identify string that identifies the meter. However, identify strings can be created for the option boards installed on a meter. In this case, the returned string can contain multiple identify strings, where the the meter's identify string is listed first and identify strings are separated by a semi- colon. Use GetIdentifyStrings to separate multiple identify strings.
The identify string is formatted as a J command and may not be suitable for showing to the user as it can contain non-printable characters. Instead, it is formatted for easy processing by a script or a program. A typical identify string returned for an A3 meter with LANOB option board follows (wrapped for clarity):
Example of A3 Identify string followed by LANOB's identify string, spaces and new lines used for clarity:
| MStdString MProtocol::IdentifyMeterWithContext | ( | bool | sessionIsStarted = false, |
| TableRawDataVector * | tablesRead = NULL |
||
| ) |
Identify the meter if the protocol is known (note this is not an ANSI Identify protocol command).
If the first parameter is true, the service assumes the session is open, and it will not start the session, or close it. The second parameter, if it is not NULL, is filled with the data from tables, which IdentifyMeter had to read from the meter during its attempts to fetch the necessary information from the meter. This table vector can be used in order to minimize the communication with the meter, if this task has its place.
| sessionIsStarted | True if the method should not start and end the session as part of identification. |
| tablesRead | Pointer of data vector for tables that were read as part of the call. |
|
inline |
Increment the number of application layer services failed.
This can be used by the outside application, which is willing to treat its actions as an application layer failure.
|
inline |
Increment the number of application layer services retried.
This can be used by the outside application, which is willing to treat its actions as an application layer retry.
|
inline |
Increment the number of application layer services successfully processed.
This can be used by the outside application, which is willing to treat its actions as an application layer service.
|
inline |
Increment the number of data link layer packets failed.
This can be used by the outside application, which is willing to treat its actions as a link layer failure.
|
inline |
Increment the number of data link layer packets retried.
This can be used by the outside application, which is willing to treat its actions as a link layer retry.
|
inline |
Increment the number of data link layer packets successfully processed.
This can be used by the outside application, which is willing to treat its actions as a link layer success.
|
inline |
Whether the channel is owned by this protocol.
When the channel is owned, it will be deleted by protocol destructor, or at the event of channel reassignment to the protocol.
| bool MProtocol::IsConnected | ( | ) | const |
Tells whether the protocol is currently connected.
This method is a straightforward facade to MChannel::IsConnected. It 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.
| bool MProtocol::IsInSession | ( | ) | const |
Whether the protocol is in session.
This is a generic method, and the meaning of 'session' depends on protocol type and mode. The notion of a session exists in most protocols, and for these protocols the property indicates whether MeteringSDK considers the device to be in session mode. The current implementation, however, does not respect session timeout, therefore, when the client protocol is in session, the device might have timed out already.
Some protocols such as MProtocolC1222 do not have session state, however for them this property will behave as if the notion of a session is present, such as:
When both this property and GetKeepSessionAlive are true, and session keeping is implemented for this protocol type or mode, the value of IsInSession will indicate whether the session keeping is being done. Session keeping sequence, however, can be interrupted by an error.
| void MProtocol::QAbort | ( | ) |
Clears the commands in the queue, or cancel the ongoing background communication.
If the queue is empty when the QAbort is issued, the queue remains empty and no error is generated. If the queue has commands, but they are not being processed (QCommit has not been issued), then the queue is cleared and no error is generated.
If the queue is being executed asynchronously (QCommit(true) then QAbort will tell MCOM to stop executing the commands in the queue and clear all remaining commands from the queue. If the abort is requested while a table is being written, the write request is completed before the abort request will be processed. No attempt is made to end (or clean up) the session. Note that QAbort returns immediately, it does not wait for the communications to stop. How long it takes for MCOM to respond to the QAbort request depends on the protocol and the tasks running on the PC. Typically, one could expect the time to be less than 500 mSec. To determine when communications have been terminated, QIsDone must be checked. For communications that have been stopped by a QAbort, QIsDone will raise an error. If QIsDone is not checked and allowed to raise the error, then the next Q Command (such as QStartSession), will raise an error. Most likely the error will indicate "Invalid operation during active background communication". This is because the asynchronous communication background thread can not terminate while there is an error to hand back to the foreground thread that started the asynchronous communications. Asynchronous communications should always check QIsDone until it is True or raises an error.
Note that QAbort and QIsDone are issued immediately, they do NOT require a QCommit.
|
virtual |
Executes all operations in MProtocol's command queue.
If no operations were queued then QCommit does nothing.
Protocol supports synchronous and asynchronous communications. When synchronous communications are initiated, QCommit will not return until all commands in the queue have been executed or an error occurs. This prevents the calling application from performing any other work on that thread. When asynchronous communications are initiated, the QCommit will return immediately while the commands in the queue are executed in the background. The calling application is free to perform other work while waiting for the communications to complete. The application will have to check QIsDone to determine when asynchronous communications have completed. The application can also call QAbort to stop and clear the commands from the queue.
Should an error occur during synchronous communications, it will be reported immediately on the QCommit. Should an error occur during asynchronous communications, the error is raised on QIsDone. In either case, no attempt is made to execute the remaining commands in the queue.
The command queue will always be cleared after a QCommit, regardless of success or failure of the operations that were queued.
| asynchronously | Whether to perform the communication on the background, asynchronously. |
The following sequences are completely equivalent:
or:
Case of background communication in a separate thread:
| void MProtocol::QConnect | ( | ) |
Places a Connect command in the queue.
The QConnect can be paired with QDisconnect or Disconnect. Protocol supports synchronous and asynchronous communications.
When synchronous communications are initiated, QCommit will not return until all commands in the queue have been executed or an error occurs. This prevents the calling application from performing any other work on that thread. When asynchronous communications are initiated, the QCommit returns immediately while the commands in the queue are executed in the background. The calling application is free to perform other work while waiting for the communications to complete. The application will have to check QIsDone to determine when asynchronous communications have completed. The application can also call QAbort to stop and clear the commands from the queue. QAbort can be useful for Connect sequences that take a long time (such as the 30-60 seconds it takes to connect to a modem).
| void MProtocol::QDisconnect | ( | ) |
Places a Disconnect command in the queue.
The QDisconnect can be paired with QConnect or Connect. Note that an commands are cleared from the queue when an error occurs. If the QDisconnect is placed in the queue and an error occurs before it can be issued, it will be cleared from the queue along with the remaining unexecuted commands. Error handling routines must issue a Disconnect (or QDisconnect/QCommit), in order to disconnect from the channel. For this reason, it is recommended that users use Disconnect instead of QDisconnect for most cases.
Protocol supports synchronous and asynchronous communications. When synchronous communications are initiated, QCommit will not return until all commands in the queue have been executed or an error occurs. This prevents the calling application from performing any other work on that thread. When asynchronous communications are initiated, the QCommit returns immediately while the commands in the queue are executed in the background. The calling application is free to perform other work while waiting for the communications to complete. The application will have to check QIsDone to determine when asynchronous communications have completed. The application can also call QAbort to stop and clear the commands from the queue.
| void MProtocol::QEndSession | ( | ) |
Adds an end session command to MProtocol's command queue.
When QEndSession is executed by a QCommit, the active session with the meter will be terminated. Typically, this is done using the protocol's logoff service. If the protocol does not support a start/end session, such as sessionless MProtocolC1222, then QEndSession does nothing and does not generate an error. This is so programs that support multiple meters and protocols can be written with the QStartSession and QEndSession.
For protocols that support start/end session, once an QEndSession command is executed, no other commands can be sent to the meter until after the next QStartSession. The communications link to the meter will not be severed by QEndSession. For instance, a modem channel will remain on-line after this operation. To sever the communications link to the meter requires using the Disconnect() method. The Disconnect method should only be used when no more communications to the meter are required.
| void MProtocol::QEndSessionNoThrow | ( | ) |
EndSessionNoThrow request is queued.
This service is part of queue communication interface. In all ways it is similar to QEndSession except that it silently swallows any error, should it appear. Therefore, this variant is very convenient in error handlers that need to ensure that the session has ended.
| void MProtocol::QFunctionExecute | ( | MCOMNumberConstRef | number | ) |
Place a function without data request in MProtocol command queue.
This service is part of queue communication interface.
| number | Identifies the function to be placed into the queue. Typically, this is an integer, but some protocols do allow it to be a string. |
| void MProtocol::QFunctionExecuteRequest | ( | MCOMNumberConstRef | number, |
| const MByteString & | request | ||
| ) |
Place a function with request data in MProtocol's command queue.
This service is part of queue communication interface.
| number | Identifies the function to be placed into the queue. Typically, this is an integer, but some protocols do allow it to be a string. |
| request | The function data to send to the meter. It must be in the form of a byte array and must have the number of bytes that corresponds to the specified function. |
| void MProtocol::QFunctionExecuteRequestResponse | ( | MCOMNumberConstRef | number, |
| const MByteString & | request, | ||
| int | id, | ||
| unsigned | estimatedResponseSize = DEFAULT_ESTIMATED_RESPONSE_SIZE |
||
| ) |
Place a function with request and response data in MProtocol's command queue.
This service is part of queue communication interface. The response data will be available after the QCommit method is issued. Use the QGetFunctionData method to retrieve the bytes.
| number | Identifies the function to be placed into the queue. Typically, this is an integer, but some protocols do allow it to be a string. |
| request | The function data to send to the meter. It must be in the form of a byte array and must have the number of bytes that corresponds to the specified function. |
| id | Operation identifier to associate with the data returned from the device. When processing tables or functions with different numbers, this can be any value, as tables and functions can be identified by their numbers, however when using the same table or function number in the same queue, this ID should be unique, so the identification is possible. |
| estimatedResponseSize | optional parameter. If provided, this is the size of the response. If not provided, this is estimated to be large enough to fit any possible value. |
| void MProtocol::QFunctionExecuteResponse | ( | MCOMNumberConstRef | number, |
| int | id, | ||
| unsigned | estimatedResponseSize = DEFAULT_ESTIMATED_RESPONSE_SIZE |
||
| ) |
Place a function with response data in MProtocol's command queue.
This service is part of queue communication interface. The response data will be available after the QCommit method is issued. Use the QGetFunctionData to retrieve the bytes.
| number | Identifies the function to be placed into the queue. Typically, this is an integer, but some protocols do allow it to be a string. |
| estimatedResponseSize | optional parameter. If provided, this is the size of the response. If not provided, this is estimated to be large enough to fit any possible value. |
| id | Operation identifier to associate with the data returned from the device. When processing tables or functions with different numbers, this can be any value, as tables and functions can be identified by their numbers, however when using the same table or function number in the same queue, this ID should be unique, so the identification is possible. |
| MByteString MProtocol::QGetFunctionData | ( | MCOMNumberConstRef | number, |
| int | id = -1 |
||
| ) |
Fetch the function response data after the function has been successfully executed in QCommit.
The data remains available after commit has performed, but until the next queue starts to be built.
| number | Number of the function that was executed, whatever is given to QFunctionExecuteResponse or QFunctionExecuteRequestResponse |
| id | If the same table was read several times in the same session, use this id to distinguish between individual calls of QTableRead or QTableReadPartial. |
| MStdString MProtocol::QGetIdentifyMeterData | ( | ) |
Fetch the identify meter string after the QIdentifyMeter has been successfully performed in QCommit.
Typically, QGetIdentifyMeterData returns only one identify string that identifies the meter. However, identify strings can be created for the option boards installed on a meter. In this case, the returned string can contain multiple identify strings, where the the meter's identify string is listed first and identify strings are separated by a semi- colon. Use GetIdentifyStrings to separate multiple identify strings.
The identify string is formatted as a J command and may not be suitable for showing to the user as it can contain non-printable characters. Instead, it is formatted for easy processing by a script or a program. A typical identify string returned for an A3 meter with LANOB option board follows (wrapped for clarity):
| MByteString MProtocol::QGetTableData | ( | MCOMNumberConstRef | number, |
| int | id = -1 |
||
| ) |
Fetch the table data after the table read has been successfully performed by QCommit.
The data remains available after commit has performed, but until the next queue starts to be built.
| number | Number of the table that was read, whatever is given to QTableRead or QTableReadPartial |
| id | If the same table was read several times in the same session, use this id to distinguish between individual calls of QTableRead or QTableReadPartial. |
| void MProtocol::QIdentifyMeter | ( | ) |
Places an IdentifyMeter task in the queue.
The commands stored in the command queue will be sent to the meter when QCommit is issued. The identify meter task identifies the meter version and other information if the protocol is known (note that this is not an ANSI Identify protocol command). Typically, QIdentifyMeter is used when creating a meter of a known type, but an unknown version.
The QIdentifyMeter service does NOT wrap the start and end session around the identification task. To use QIdentifyMeter, one has to connect to the meter and start the session. This differs from IdentifyMeter which wraps start and end session around the identification task.
The identification information is retrieved with QGetIdentifyMeterData after QIdentifyMeter has been successfully QCommit-ted (all requests in queue sent to the meter).
|
inline |
True if the background communication is still progressing.
This is different from QIsDone in the sense that it will be true only if there is a background activity.
| bool MProtocol::QIsDone | ( | ) |
Combines QNeedToCommit with the following QCommit in case all commands in the queue have been sent.
The relationship of this property with QNeedToCommit is shown below:
This property is used when QCommit was issued asynchronously. During asynchronous communications, the application is free to perform other work while waiting for the communications to complete. The application can periodically check QIsDone to determine if MCOM has completed processing the commands in the queue. For asynchronous communications, QIsDone will raise any communication errors. (For synchronous communications, any errors will be raised on QCommit.)
Asynchronous communications should check QIsDone until it reports True or raises an error. The asynchronous communication background thread can not terminate until QIsDone has been checked and it reports True or raises an error. If QIsDone is not checked until one of these states occur, then the next Q Command (such as QStartSession), will raise an error, even if the communications have completed. Most likely the error will indicate "Invalid operation during active background communication".
Note that QIsDone and QAbort are issued immediately, they do NOT require a QCommit.
| bool MProtocol::QNeedToCommit | ( | ) | const |
Whether or not it is time to call QCommit(true) in order to sync with the background thread.
In case M_NO_MCOM_PROTOCOL_THREAD is nonzero during compilation, this service is not present. Asynchronous communication will not be supported in this case.
| void MProtocol::QStartSession | ( | ) |
Adds a start session command to MProtocol's command queue.
QStartSession performs the protocol services required to gain access to the meter, so that tables can be read and written and functions can be executed. Before committing the start session request, a connection with the meter must have been established using Connect() or QConnect.
When QStartSession is executed by QCommit, an active session with the meter is initiated. The start session action is not a single protocol command but rather a sequence of commands that establish an active communication session with the meter. Generally this sequence of commands handles handshaking with the meter, presenting a password, receiving permission to proceed, and negotiating various protocol settings. The exact sequence of steps performed by this method depends on the MProtocol Type. If the protocol does not support a start session, then QStartSession does nothing and does not generate an error. This is so programs that support multiple meters and protocols can be written with the QStartSession and QEndSession.
| void MProtocol::QTableRead | ( | MCOMNumberConstRef | number, |
| unsigned | expectedSize, | ||
| int | id | ||
| ) |
Adds a ReadTable command to MProtocol's command queue.
This service is part of queue communication interface. The result table data can be retrieved by using the QGetTableData method.
| number | Identifies the table to be placed into the queue. The format is protocol dependent. In can be a numeric value, as for the case of MProtocolC1218 or MProtocolC1222, or even a string if the protocol supports strings. |
| expectedSize | Expected table size in bytes. If this is zero, then the entire table will be read. If the protocol does not support full table reads then specifying a size of zero will result in an error being generated. |
| id | Operation identifier to associate with the data returned from the device. When processing tables or functions with different numbers, this can be any value, as tables and functions can be identified by their numbers, however when using the same table or function number in the same queue, this ID should be unique, so the identification is possible. |
| void MProtocol::QTableReadPartial | ( | MCOMNumberConstRef | number, |
| int | offset, | ||
| int | size, | ||
| int | id | ||
| ) |
Adds a partial table read command to MProtocol's command queue.
This service is part of queue communication interface.
| number | Identifies the table to be placed into the queue. The format is protocol dependent. In can be a numeric value, as for the case of MProtocolC1218 or MProtocolC1222, or even a string if the protocol supports it. |
| offset | The number of bytes from the beginning of the table where the operation will begin. |
| size | The number of bytes to be read starting from offset. |
| id | Operation identifier to associate with the data returned from the device. When processing tables or functions with different numbers, this can be any value, as tables and functions can be identified by their numbers, however when using the same table or function number in the same queue, this ID should be unique, so the identification is possible. |
| void MProtocol::QTableWrite | ( | MCOMNumberConstRef | number, |
| const MByteString & | data | ||
| ) |
Adds a table write command to MProtocol's command queue.
This service is part of queue communication interface.
| number | Identifies the table to be placed into the queue. The format is protocol dependent. In can be a numeric value, as for the case of MProtocolC1218 or MProtocolC1222, or even a string if the protocol supports it. |
| data | This buffer contains the data that will be written to the meter. The size of data determines the size of the buffer to be written. |
| void MProtocol::QTableWritePartial | ( | MCOMNumberConstRef | number, |
| const MByteString & | data, | ||
| int | offset | ||
| ) |
Adds a partial table write command to MProtocol's command queue.
This service is part of queue communication interface.
| number | Identifies the table to be placed into the queue. The format is protocol dependent. In can be a numeric value, as for the case of MProtocolC1218 or MProtocolC1222, or even a string if the protocol supports it. |
| data | This buffer contains the data that will be written to the meter. The size of data determines the size of the buffer to be written. |
| offset | The number of bytes from the beginning of the table where the write operation will begin. |
| void MProtocol::QWriteToMonitor | ( | const MStdString & | message | ) |
Add the message to write to the Monitor log file to MProtocol's command queue.
The QWriteToMonitor method can be used to make communication transactions more readable by marking key data transactions, such as the start/end of a test.
QWriteToMonitor must be issued after the connection is established with the end device (Connect or QConnect). QWriteToMonitor is different than MMonitor::Write in that Write sends the message to the monitor immediately, whereas QWriteToMonitor is executed as part of the command queue on QCommit.
No error is thrown if the Monitor is not listening or the log file is not accumulating.
| message | The message to write to the Monitor log file. |
| Muint8 MProtocol::ReadStartByte | ( | const MByteString & | setOfValidStartBytes, |
| unsigned | trafficTimeout | ||
| ) |
Read the start byte of the packet in a proper way, taking into consideration timeouts and ignoring garbage.
| setOfValidStartBytes | - sequence of bytes that are valid start characters. |
| trafficTimeout | - how long to wait for arrival of start byte. |
| void MProtocol::ResetCounts | ( | ) |
Clear the statistical data for the channel.
Zeroes Out the COUNT_* and *_ROUND_TRIP_TIME properties. The list of properties that are reset follows:
If the channel is present, its own MChannel::ResetCounts() is called and channel's counts are reset.
| void MProtocol::SetChannel | ( | MChannel * | channel | ) |
Channel associated with this protocol.
When the channel is owned, and a new one is reassigned to the protocol, the previous channel will be deleted.
|
inline |
Whether the channel is owned by this protocol.
When the channel is owned, it will be deleted by protocol destructor, or at the event of channel reassignment to the protocol.
| void MProtocol::SetKeepSessionAlive | ( | bool | alive | ) |
Whether the protocol should keep session alive in case of long inactivity.
When KeepSessionAlive is true, the session is kept from timing out. The feature can also be used to prevent an idling connection from being closed. What is done to keep the session alive is protocol dependent, but usually involves repeatedly sending some type of communication request to the meter. For some sessionless protocols this property has no effect.
The session is being kept alive by a background thread that is watching for the current value of property IsInSession. When IsInSession is true, the background communication is performed. Errors raised on the background can be silenced if IsConnected value was false. Otherwise, the session keeping errors will be thrown to the foreground thread at the next communication event, such as QCommit. Another place that checks and throws an error collected by the background thread is the assignment to KeepSessionAlive property itself. Therefore, the following will check for an error, and throw it if it was present:
When KeepSessionAlive is false, the session will time out or the connection will be closed according to the protocol rules.
|
inline |
Primary data order of the device, whether it is little endian.
This information is used by some protocol implementations, for example, for ANSI procedures/functions implementation. Such protocols have application-level fields that depend on the protocol byte order.
It is only necessary to set this property when communicating to a device of different endianity as the protocol default. When communicating through the upper library levels this property can be set automatically.
| void MProtocol::SetPassword | ( | const MByteString & | password | ) |
Application level password of the protocol.
The Password property is the binary value that is used to gain access to the device. No interpretation of C escape character sequences is performed on this string.
Many protocols will typically use password in the StartSession sequence, while some, such as sessionless mode of MProtocolC1222, will send password at every request.
The password can have less characters than the maximum number of characters allowed. In this case, during the communication, the password will be padded with a fill character (different for each protocol). For example, if an 8 character password is set to "1111", then the password "1111 " is transmitted during communications, while Password property will continue to report "1111". The padded characters are significant, and the password stored in the meter must exactly match the password used during communications (including the fill characters) or an error is generated.
| void MProtocol::SetPasswordList | ( | const MByteStringVector & | passwordList | ) |
Password list for the protocol.
The password lists, when not empty, overwrite the SetPassword property. In such case, passwords from the password list are applied in the ascending order until a successful entry is found. If none exists, the last error received during list processing is thrown.
|
inline |
Access to the progress monitor, if exists
| void MProtocol::Sleep | ( | unsigned | milliseconds | ) |
Calls channel's Sleep method if the channel is present.
Channel's sleep is interruptible, and this is the difference of this method from plain MUtilities::Sleep.
| milliseconds | How many milliseconds to sleep. |
| void MProtocol::StartSession | ( | ) |
Synchronously start the session.
Depending on the particular protocol this leads to a sequence of handshake and logon commands.
See QStartSession for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
|
static |
Compute checksum of the byte string given as parameters.
The checksum is calculated based on the C12 rules. Different protocols can have their own variants of this method.
| buffer | The buffer for which to calculate the checksum. |
|
static |
Most popular one-byte checksum calculation procedure, a sum of all bytes.
The checksum is calculated based on the C12 rules. Different protocols can have their own variants of this method.
| buff | The pointer to the buffer for which to calculate the checksum. |
| size | Size of the buffer. |
| MByteString MProtocol::TableRead | ( | MCOMNumberConstRef | number, |
| unsigned | expectedSize = 0 |
||
| ) |
Synchronously read the whole table with number given as parameter.
See QTableRead for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
The third argument is introduced to handle a special case where the table size is bigger than what the protocol allows, such as configuring an ANSI meter to have more load profile data than the 64K that can be transmitted with ANSI C12.18. In this case the table is read with multiple partial reads, where each partial read is sized to fit within the protocol constraints.
| number | Table number. |
| expectedSize | If given, should match exactly the size of the table. |
| void MProtocol::TableReadBuffer | ( | MCOMNumberConstRef | number, |
| void * | buff, | ||
| unsigned | size | ||
| ) |
Same as ReadTable, but instead of returning a byte string, read table into a given buffer.
| number | Table number. |
| buff | Where to return the table bytes. |
| size | Size of the given buffer and size of the table. |
|
inline |
Same as ReadTable, but instead of returning a byte string, read table into a given template variable.
| MByteString MProtocol::TableReadNoThrow | ( | MCOMNumberConstRef | number, |
| MException ** | exception, | ||
| unsigned | expectedSize = 0 |
||
| ) |
Synchronously read the whole table with number given as parameter, do not throw an exception, but rather return it.
See QTableRead for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
The second argument is introduced to handle exceptions internally and return the data that was successfully read before the exception was raised.
The third argument is introduced to handle a special case where the table size is bigger than what the protocol allows, such as configuring an ANSI meter to have more load profile data than the 64K that can be transmitted with ANSI C12.18. In this case the table is read with multiple partial reads, where each partial read is sized to fit within the protocol constraints.
| number | Table number. |
| exception | Returned new object, exception, if it was thrown during the operation. If not NULL, it has to be deleted by the caller. |
| expectedSize | If given, should match exactly the size of the table. |
| MByteString MProtocol::TableReadPartial | ( | MCOMNumberConstRef | number, |
| int | offset, | ||
| int | size | ||
| ) |
Synchronously read part of the table with number given as parameter.
See QTableReadPartial for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Table number. |
| offset | Offset within the table. |
| size | Size within the table starting from the offset. |
| void MProtocol::TableReadPartialBuffer | ( | MCOMNumberConstRef | number, |
| int | offset, | ||
| void * | buff, | ||
| unsigned | size | ||
| ) |
Same as TableReadPartial, but instead of returning a byte string, read table into a given buffer.
| number | Table number. |
| offset | Offset within the table. |
| buff | Where to return the table bytes. |
| size | Size of the partial chunk and size of buff. |
|
inline |
Same as TableReadPartial, but instead of returning a byte string, partially read table into a given template variable.
| number | Table number. |
| table | Table raw structure or class. |
| offset | Offset within the table. |
| void MProtocol::TableWrite | ( | MCOMNumberConstRef | number, |
| const MByteString & | data | ||
| ) |
Synchronously write the whole table with number given as parameter.
See QTableWrite for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Table number. |
| data | Table data to be written. |
| void MProtocol::TableWriteBuffer | ( | MCOMNumberConstRef | number, |
| const void * | data, | ||
| unsigned | size | ||
| ) |
Same as TableWrite, but uses buffer, given as data and size parameters.
| number | Table number. |
| data | Pointer to table data to be written. |
| size | Size of the table data. |
|
inline |
Same as WriteTable, but uses variable of some specific template class or structure.
| number | Table number. |
| table | Table raw structure or class. |
| void MProtocol::TableWritePartial | ( | MCOMNumberConstRef | number, |
| const MByteString & | data, | ||
| int | offset | ||
| ) |
Synchronously write part of the table with number given as parameter.
See QTableWritePartial for the queue version of this service. Q services would work faster for the queue based protocols, but slower for synchronous protocols like C12. Also, they are obviously less convenient for synchronous operations.
| number | Table number. |
| data | Table data to be written at a given offset. |
| offset | Offset within the table. |
| void MProtocol::TableWritePartialBuffer | ( | MCOMNumberConstRef | number, |
| int | offset, | ||
| const void * | buff, | ||
| unsigned | size | ||
| ) |
Same as TableWritePartial, but instead of using a byte string, write table using a given buffer.
| number | Table number. |
| offset | Offset within the table. |
| buff | Pointer to table data to be written at a given offset. |
| size | Size of the data. |
|
inline |
Same as TableWritePartial, but instead of using a byte string, write table using a given template class contents.
| number | Table number. |
| table | Table raw structure or class. |
| offset | Offset within the table. |
| void MProtocol::WriteCountsToMonitor | ( | ) |
Write running values of communication quality counters to monitor.
This is a convenience method for all types of troubleshooting. No errors are thrown. If there is no monitor connected, nothing is done.
|
virtual |
Synchronously write a message to the monitor, if it is connected.
No error is thrown if the Monitor is not listening or the log file is not accumulating.
| message | The message to write to the Monitor log file. |
Reimplemented from MCOMObject.
1.8.11 
