Revision control
++ // Copyright (C) 2022 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++ #include "qcanmessagedescription.h"
++ #include "qcanmessagedescription_p.h"
++ #include "qcansignaldescription.h"
++
++ #include <QtCore/QHash>
++ #include <QtCore/QSharedData>
++
++ QT_BEGIN_NAMESPACE
++
++ /*!
++ \class QCanMessageDescription
++ \inmodule QtSerialBus
++ \since 6.5
++ \preliminary
++
++ \brief The QCanMessageDescription class describes the rules to process a CAN
++ message and represent it in an application-defined format.
++
++ A CAN message is basically a \l QCanBusFrame. The description of a CAN
++ message includes the following:
++ \list
++ \li Message ID.
++ \li Message name.
++ \li Message length in bytes.
++ \li Source of the message (transmitter).
++ \li Description of signals in the message.
++ \endlist
++
++ The QCanMessageDescription class provides methods to control all those
++ parameters.
++
++ \section1 Message ID
++ The message ID is a unique identifier, which is used to select the proper
++ message description when decoding the incoming \l QCanBusFrame or encoding
++ a \l QCanBusFrame based on the provided data.
++
++ See \l QCanUniqueIdDescription documentation for more details on the unique
++ identifier description.
++
++ \section1 Signal Description
++ The signal description is represented by the \l QCanSignalDescription
++ class. The QCanMessageDescription class only provides a list of signals that
++ belong to the message.
++
++ \sa QCanSignalDescription, QCanUniqueIdDescription
++ */
++
++ /*!
++ Creates an empty message description.
++ */
++ QCanMessageDescription::QCanMessageDescription() : d(new QCanMessageDescriptionPrivate)
++ {
++ }
++
++ /*!
++ Creates a message description with the values copied from \a other.
++ */
++ QCanMessageDescription::QCanMessageDescription(const QCanMessageDescription &other) : d(other.d)
++ {
++ }
++
++ /*!
++ \fn QCanMessageDescription::QCanMessageDescription(QCanMessageDescription &&other) noexcept
++
++ Creates a message description by moving from \a other.
++
++ \note The moved-from QCanMessageDescription object can only be destroyed or
++ assigned to. The effect of calling other functions than the destructor or
++ one of the assignment operators is undefined.
++ */
++
++ /*!
++ \fn QCanMessageDescription::~QCanMessageDescription()
++
++ Destroys this message description.
++ */
++
++ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QCanMessageDescriptionPrivate)
++
++ /*!
++ Assigns the values from \a other to this message description.
++ */
++ QCanMessageDescription &QCanMessageDescription::operator=(const QCanMessageDescription &other)
++ {
++ d = other.d;
++ return *this;
++ }
++
++ /*!
++ \fn QCanMessageDescription &QCanMessageDescription::operator=(QCanMessageDescription &&other) noexcept
++
++ Move-assigns the values from \a other to this message description.
++
++ \note The moved-from QCanMessageDescription object can only be destroyed or
++ assigned to. The effect of calling other functions than the destructor or
++ one of the assignment operators is undefined.
++ */
++
++ /*!
++ Returns \c true when the message description is valid and \c false
++ otherwise.
++
++ A valid message description \e must have at least one signal description.
++ All signal descriptions \e must be valid as well.
++
++ \sa signalDescriptions(), QCanSignalDescription::isValid()
++ */
++ bool QCanMessageDescription::isValid() const
++ {
++ if (d->messageSignals.isEmpty())
++ return false;
++
++ for (const auto &sigDesc : d->messageSignals) {
++ if (!sigDesc.isValid())
++ return false;
++ }
++
++ return true;
++ }
++
++ /*!
++ Returns the unique identifier of the CAN message.
++
++ See the \l {Message ID} section for more information about the unique
++ identifier.
++
++ \sa setUniqueId()
++ */
++ QtCanBus::UniqueId QCanMessageDescription::uniqueId() const
++ {
++ return d->id;
++ }
++
++ /*!
++ Sets the unique identifier of the CAN message to \a id.
++
++ See the \l {Message ID} section for more information about the unique
++ identifier.
++
++ \sa uniqueId()
++ */
++ void QCanMessageDescription::setUniqueId(QtCanBus::UniqueId id)
++ {
++ d.detach();
++ d->id = id;
++ }
++
++ /*!
++ Returns the name of the CAN message.
++
++ //! [qcanmessagedesc-aux-parameter]
++ This parameter is introduced only for extra description. It's not used
++ during message encoding or decoding.
++ //! [qcanmessagedesc-aux-parameter]
++
++ \sa setName()
++ */
++ QString QCanMessageDescription::name() const
++ {
++ return d->name;
++ }
++
++ /*!
++ Sets the name of the CAN message to \a name.
++
++ \include qcanmessagedescription.cpp qcanmessagedesc-aux-parameter
++
++ \sa name()
++ */
++ void QCanMessageDescription::setName(const QString &name)
++ {
++ d.detach();
++ d->name = name;
++ }
++
++ /*!
++ Returns the size in bytes of the CAN message.
++
++ \sa setSize()
++ */
++ quint8 QCanMessageDescription::size() const
++ {
++ return d->size;
++ }
++
++ /*!
++ Sets the size in bytes of the CAN message to \a size.
++
++ \sa size()
++ */
++ void QCanMessageDescription::setSize(quint8 size)
++ {
++ d.detach();
++ d->size = size;
++ }
++
++ /*!
++ Returns the transmitter node of the message.
++
++ \include qcanmessagedescription.cpp qcanmessagedesc-aux-parameter
++
++ \sa setTransmitter()
++ */
++ QString QCanMessageDescription::transmitter() const
++ {
++ return d->transmitter;
++ }
++
++ /*!
++ Sets the transmitter node of the message to \a transmitter.
++
++ \include qcanmessagedescription.cpp qcanmessagedesc-aux-parameter
++
++ \sa transmitter()
++ */
++ void QCanMessageDescription::setTransmitter(const QString &transmitter)
++ {
++ d.detach();
++ d->transmitter = transmitter;
++ }
++
++ /*!
++ Returns the comment for the message.
++
++ \include qcanmessagedescription.cpp qcanmessagedesc-aux-parameter
++
++ \sa setComment()
++ */
++ QString QCanMessageDescription::comment() const
++ {
++ return d->comment;
++ }
++
++ /*!
++ Sets the comment for the message to \a text.
++
++ \include qcanmessagedescription.cpp qcanmessagedesc-aux-parameter
++
++ \sa comment()
++ */
++ void QCanMessageDescription::setComment(const QString &text)
++ {
++ d.detach();
++ d->comment = text;
++ }
++
++ /*!
++ Returns the list of signal descriptions that belong to this message
++ description.
++
++ \sa signalDescriptionForName(), addSignalDescription(),
++ setSignalDescriptions(), clearSignalDescriptions()
++ */
++ QList<QCanSignalDescription> QCanMessageDescription::signalDescriptions() const
++ {
++ return QList<QCanSignalDescription>(d->messageSignals.cbegin(), d->messageSignals.cend());
++ }
++
++ /*!
++ Returns the signal description of a signal with the name \a name.
++
++ If the message description does not have such signal description, a
++ default-constructed \l QCanSignalDescription object is returned.
++
++ \sa signalDescriptions(), addSignalDescription(), setSignalDescriptions(),
++ clearSignalDescriptions()
++ */
++ QCanSignalDescription QCanMessageDescription::signalDescriptionForName(const QString &name) const
++ {
++ return d->messageSignals.value(name);
++ }
++
++ /*!
++ Clears all the signal descriptions of this message.
++
++ \sa signalDescriptions(), signalDescriptionForName(),
++ addSignalDescription(), setSignalDescriptions()
++ */
++ void QCanMessageDescription::clearSignalDescriptions()
++ {
++ d.detach();
++ d->messageSignals.clear();
++ }
++
++ /*!
++ Adds a new signal description \a description to this message description.
++
++ If the message description already has a signal description for a signal
++ with the same name, it is overwritten.
++
++ \sa signalDescriptions(), signalDescriptionForName(),
++ setSignalDescriptions(), clearSignalDescriptions()
++ */
++ void QCanMessageDescription::addSignalDescription(const QCanSignalDescription &description)
++ {
++ d.detach();
++ d->messageSignals.insert(description.name(), description);
++ }
++
++ /*!
++ Sets the descriptions of the signals belonging to this message description
++ to \a descriptions.
++
++ \note Message description \e must have signal descriptions with unique
++ signal names, so if the \a descriptions list contains entries with
++ duplicated names, only the last entry will be added.
++
++ \sa signalDescriptions(), signalDescriptionForName(),
++ addSignalDescription(), clearSignalDescriptions()
++ */
++ void QCanMessageDescription::setSignalDescriptions(const QList<QCanSignalDescription> &descriptions)
++ {
++ d.detach();
++ d->messageSignals.clear();
++ d->messageSignals.reserve(descriptions.size());
++ for (const auto &desc : descriptions)
++ d->messageSignals.insert(desc.name(), desc);
++ }
++
++ #ifndef QT_NO_DEBUG_STREAM
++ QDebug QCanMessageDescription::debugStreaming(QDebug dbg, const QCanMessageDescription &msg)
++ {
++ QDebugStateSaver saver(dbg);
++ dbg.nospace() << "QCanMessageDescription(" << msg.name() << ", ID = " << msg.uniqueId()
++ << ", Size = " << msg.size();
++ if (!msg.transmitter().isEmpty())
++ dbg << ", Transmitter = " << msg.transmitter();
++ if (!msg.comment().isEmpty())
++ dbg << ", Comment = " << msg.comment();
++ const auto msgSignals = msg.signalDescriptions();
++ if (!msgSignals.isEmpty()) {
++ dbg << ", Signals: {";
++ bool first = true;
++ for (const auto &sig : msgSignals) {
++ if (!first)
++ dbg << ", ";
++ dbg << sig;
++ first = false;
++ }
++ dbg << "}";
++ }
++ dbg << ")";
++ return dbg;
++ }
++ #endif // QT_NO_DEBUG_STREAM
++
++ QCanMessageDescriptionPrivate *QCanMessageDescriptionPrivate::get(const QCanMessageDescription &desc)
++ {
++ return desc.d.data();
++ }
++
++ QT_END_NAMESPACE