/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
    \page qtserialbus-socketcan-overview.html
    \title Using SocketCAN Backend

    \brief Overview of how to use the SocketCAN backend.

    The SocketCAN backend encapsulates the Linux sockets API for accessing the CAN devices.
    This API is a set of open source CAN drivers and a networking stack contributed by
    Volkswagen Research to the Linux kernel.

    \section1 Creating CAN Bus Devices

    At first it is necessary to check that QCanBus provides the desired backend:

    \code
        foreach (const QByteArray &backend, QCanBus::instance()->plugins()) {
            if (backend == "socketcan") {
                // were found
                break;
            }
        }
    \endcode

    Where, \e socketcan is the backend name.

    Further, it is necessary to request from QCanBus the device with the active SocketCAN
    interface:

    \code
        QCanBusDevice *device = QCanBus::instance()->createDevice("socketcan", QStringLiteral("can0"));
        device->connectDevice();
    \endcode

    Where, \e can0 is the active CAN interface name. CAN interfaces act like regular network interfaces
    on Linux systems and can be discovered using \c ifconfig.

    The device is now open and can be written and read:

    \code
        QCanBusFrame frame;
        frame.setFrameId(8);
        QByteArray payload("A36E");
        frame.setPayload(payload);
        device->writeFrame(frame);
    \endcode

    The reading can be done using the \l {QCanBusDevice::}{readFrame()} method. The
    \l {QCanBusDevice::}{framesReceived()} signal is emitted when a new frame is available
    for reading:

    \code
    QCanBusFrame frame = device->readFrame();
    \endcode

    SocketCAN supports the following configurations that can be controlled through
    \l {QCanBusDevice::}{setConfigurationParameter()}:

    \table
        \header
            \li Configuration parameter key
            \li Description
        \row
            \li QCanBusDevice::LoopbackKey
            \li To meet the multiple-user needs, the local loopback is enabled by default.
        \row
            \li QCanBusDevice::ReceiveOwnKey
            \li The reception of the CAN frames on the same socket that was sending the CAN frame
                is disabled by default.
        \row
            \li QCanBusDevice::ErrorFilterKey
            \li A CAN interface driver can generate so called \e {Error Message Frames} that can
                optionally be passed to the user application in the same way as other CAN frames.
                The possible errors are divided into different error classes that may be filtered
                using the appropriate error mask. The values for the error mask are defined in
                \c {linux/can/error.h}.
        \row
            \li QCanBusDevice::RawFilterKey
            \li This configuration can contain multiple filters of type \l QCanBusDevice::Filter.
                By default, the connection is configured to accept any CAN bus message.
        \row
            \li QCanBusDevice::BitRateKey
            \li This configuration is not supported by the socketcan backend. However
            it is possible to set the rate when configuring the CAN network interface using the \c {ip link} command.
        \row
            \li QCanBusDevice::CanFdKey
            \li This configuration option determines whether CANFD frames may be sent or received.
                By default, this option is disabled. It controls controls the CAN_RAW_FD_FRAMES
                option of the CAN socket.
    \endtable

    For example:

    \snippet snippetmain.cpp SocketCan Filter Example

    Efficient frame format and flexible data-rate are supported in SocketCAN.
 */
