path: root/src/serialbus/qcanmessagedescription.cpp

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

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

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

    \section2 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.
*/

/*!
    \fn bool QCanMessageDescription::operator==(const QCanMessageDescription &lhs, const QCanMessageDescription &rhs)

    Returns \c true if all of the \a lhs object's values are the same as those
    of \a rhs. Otherwise returns \c false.
*/

/*!
    \fn bool QCanMessageDescription::operator!=(const QCanMessageDescription &lhs, const QCanMessageDescription &rhs)

    Returns \c true if any of the \a lhs object's values are not the same as
    those of \a rhs. Otherwise returns \c false.
*/

/*!
    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);
}

bool QCanMessageDescription::equals(const QCanMessageDescription &lhs, const QCanMessageDescription &rhs)
{
    return lhs.d->name == rhs.d->name
            && lhs.d->transmitter == rhs.d->transmitter
            && lhs.d->comment == rhs.d->comment
            && lhs.d->id == rhs.d->id
            && lhs.d->size == rhs.d->size
            && lhs.d->messageSignals == rhs.d->messageSignals;
}

#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