QCanFrameProcessor Class
The QCanFrameProcessor class can be used to decode a QCanBusFrame or to convert the input data into a QCanBusFrame that is ready to be sent to the receiver. More...
| Header: | #include <QCanFrameProcessor> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SerialBus) target_link_libraries(mytarget PRIVATE Qt6::SerialBus) |
| qmake: | QT += serialbus |
| Since: | Qt 6.5 |
| Status: | Preliminary |
This class is under development and is subject to change.
Public Types
(since 6.5) struct | ParseResult |
| enum class | Error { None, InvalidFrame, UnsupportedFrameFormat, Decoding, Encoding } |
Public Functions
| QCanFrameProcessor() | |
| ~QCanFrameProcessor() | |
| void | addMessageDescriptions(const QList<QCanMessageDescription> &descriptions) |
| void | clearMessageDescriptions() |
| QCanFrameProcessor::Error | error() const |
| QString | errorString() const |
| QList<QCanMessageDescription> | messageDescriptions() const |
| QCanFrameProcessor::ParseResult | parseFrame(const QCanBusFrame &frame) |
| QCanBusFrame | prepareFrame(QtCanBus::UniqueId uniqueId, const QVariantMap &signalValues) |
| void | setMessageDescriptions(const QList<QCanMessageDescription> &descriptions) |
| void | setUniqueIdDescription(const QCanUniqueIdDescription &description) |
| QCanUniqueIdDescription | uniqueIdDescription() const |
| QStringList | warnings() const |
Detailed Description
The QCanFrameProcessor class operates on the CAN message descriptions (represented by the QCanMessageDescription and QCanSignalDescription classes) and a unique identifier description (represented by QCanUniqueIdDescription). It uses the descriptions to decode the incoming QCanBusFrame or to encode the user-specified data into the proper payload.
Before doing any decoding or encoding, the QCanFrameProcessor instance must be initialized properly. The following data needs to be provided:
- A valid unique identifier description. Use the setUniqueIdDescription() method to provide a proper description.
- At least one message description. Use the addMessageDescriptions() or setMessageDescriptions() method to provide message descriptions. All message descriptions must have distinct unique identifiers. Each message can contain multiple signal descriptions, but signal names within one message must be unique as well.
The parseFrame() method can be used to process the incoming QCanBusFrame. The method returns a ParseResult structure which contains the unique identifier and the signal values map. The keys of the map are the signal names, and the values of the map are signal values.
The prepareFrame() method can be used to generate a QCanBusFrame object for a specific unique identifier, using the provided signal names and desired values.
Errors can occur during the encoding or decoding process. In such cases the error() and errorString() methods can be used to get the information about the error.
Some non-critical problems may occur as well. Such problems will be logged, but the process will not be stopped. After the process is completed, the warnings() method can be used to access the list of all the warnings.
Note: The last error and error description, as well as the warnings, are reset once the decoding or encoding is started.
See also QCanMessageDescription and QCanSignalDescription.
Member Type Documentation
enum class QCanFrameProcessor::Error
This enum represents the possible errors that can occur while encoding or decoding the QCanBusFrame.
| Constant | Value | Description |
|---|---|---|
QCanFrameProcessor::Error::None | 0 | No error occurred. |
QCanFrameProcessor::Error::InvalidFrame | 1 | The received frame is invalid and cannot be parsed. |
QCanFrameProcessor::Error::UnsupportedFrameFormat | 2 | The format of the received frame is not supported and cannot be parsed. |
QCanFrameProcessor::Error::Decoding | 3 | An error occurred during decoding. Use errorString() to get a string representation of the error. |
QCanFrameProcessor::Error::Encoding | 4 | An error occurred during encoding. Use errorString() to get a string representation of the error. |
Member Function Documentation
QCanFrameProcessor::QCanFrameProcessor()
Creates a CAN frame processor.
[noexcept] QCanFrameProcessor::~QCanFrameProcessor()
Destroys this frame processor.
void QCanFrameProcessor::addMessageDescriptions(const QList<QCanMessageDescription> &descriptions)
Adds new message descriptions descriptions to the available message descriptions.
All message descriptions should have distinct unique ids.
If some message descriptions have repeated unique ids, only the last description will be used.
If the parser already had a message description with the same unique id, it will be overwritten.
See also messageDescriptions(), setMessageDescriptions(), and clearMessageDescriptions().
void QCanFrameProcessor::clearMessageDescriptions()
Removes all message descriptions for this frame processor.
See also messageDescriptions(), addMessageDescriptions(), and setMessageDescriptions().
QCanFrameProcessor::Error QCanFrameProcessor::error() const
Returns the last error.
See also errorString(), prepareFrame(), and parseFrame().
QString QCanFrameProcessor::errorString() const
Returns the text description of the last error.
See also error(), prepareFrame(), and parseFrame().
QList<QCanMessageDescription> QCanFrameProcessor::messageDescriptions() const
Returns all the message descriptions that are currently used by this frame processor.
See also addMessageDescriptions(), setMessageDescriptions(), and clearMessageDescriptions().
QCanFrameProcessor::ParseResult QCanFrameProcessor::parseFrame(const QCanBusFrame &frame)
Parses the frame frame using the specified message descriptions.
The process of parsing is as follows:
- The uniqueIdDescription() is used to extract the unique identifier of the message.
- The extracted unique identifier is used to search for a suitable QCanMessageDescription from the list of all available messageDescriptions().
- The matching QCanMessageDescription is used to extract the signal values from the frame.
This method returns a QCanFrameProcessor::ParseResult, which contains both the extracted unique identifier and a QVariantMap with the signals and their values. The keys of the map are the signal names, and the values of the map are signal values.
If an error occurred during the decoding, a result with empty signalValues is returned. In such cases, the error() and errorString() methods can be used to get information about the errors.
Note: Calling this method clears all previous errors and warnings.
See also addMessageDescriptions(), error(), errorString(), and warnings().
QCanBusFrame QCanFrameProcessor::prepareFrame(QtCanBus::UniqueId uniqueId, const QVariantMap &signalValues)
Constructs a CAN data frame, using uniqueId and signalValues and returns the constructed QCanBusFrame.
The signalValues parameter must contain signal names as keys, and expected signal values as values.
The process of creating the frame is as follows:
- The uniqueId is used to find an appropriate message description.
- If the message description is found, a QCanBusFrame with a payload of the specified size is created. All bytes of the payload, as well as the frame id, are initialized to zeros.
- The uniqueIdDescription() is used to encode the uniqueId into the appropriate part of the frame (frame id or payload).
- The selected message description is used to encode all the signalValues into the frame.
- The parts of the frame that are not covered by a unique id or existing signal descriptions are untouched (and so still contain zeros).
If an error occurred during the encoding, an invalid QCanBusFrame is returned. In such cases, the error() and errorString() methods can be used to get information about the errors.
Note: Calling this method clears all previous errors and warnings.
See also addMessageDescriptions(), error(), errorString(), and warnings().
void QCanFrameProcessor::setMessageDescriptions(const QList<QCanMessageDescription> &descriptions)
Replaces current message descriptions used by this frame processor with the new message descriptions descriptions.
See also messageDescriptions(), addMessageDescriptions(), and clearMessageDescriptions().
void QCanFrameProcessor::setUniqueIdDescription(const QCanUniqueIdDescription &description)
Sets the unique identifier description to description.
The unique identifier description must be valid in order to encode or decode the CAN bus frames. See the QCanUniqueIdDescription class documentation for more details.
See also uniqueIdDescription() and QCanUniqueIdDescription.
QCanUniqueIdDescription QCanFrameProcessor::uniqueIdDescription() const
Returns the unique identifier description.
The unique identifier description must be valid in order to encode or decode the CAN bus frames. See the QCanUniqueIdDescription class documentation for more details.
See also setUniqueIdDescription() and QCanUniqueIdDescription.
QStringList QCanFrameProcessor::warnings() const
Returns the list of warnings generated during the last encoding or decoding call.
See also error(), errorString(), prepareFrame(), and parseFrame().
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
