/****************************************************************************
**
** Copyright (C) 2017 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the QtIvi module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite 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 https://www.qt.io/terms-conditions.
** For further information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page reference-api.html
\title Using the Qt IVI Reference API

\section1 Overview

The Qt IVI module contains a reference API providing interfaces to common automotive
functionality. These APIs rely on the separation of the front-end API and the backend
implementation. The Qt IVI module also introduces a set of concepts used in the APIs:
zones and property attributes.

The feature areas covered by the Qt IVI module reference API are:

\list
    \li Vehicle Functions
    \list
        \li \l {QIviClimateControl} {Climate Control}
        \li \l {QIviWindowControl} {Window Control}
    \endlist
\omit
    \li Media Management
    \list
        \li Search and Browser
        \li Playqueue Management
        \li Playback Control
    \endlist
\endomit
\endlist

\chapter Key Concepts

All Qt IVI feature APIs depend on a set of key concepts. These are explained in the
following sections.

\section2 Loading Backends

As the implementation of each feature is separate from the API definition, all features
have an QIviAbstractFeature::isValid property. Until this value is \c true, the API is
effectively disabled and only return safe default values.

For more detailed information about the backend loading status, the
QIviAbstractFeature::discoveryResult property is provided. It can be used to detect backend
loading errors.

The backend loading behavior is controlled through the QIviAbstractFeature::discoveryMode
property from QML, or by calling QIviAbstractFeature::startAutoDiscovery() from C++.

In most cases, each front-end has a single corresponding backend, that is, there is commonly
only a single climate control system in each vehicle. In these cases, setting
QIviAbstractFeature::discoveryMode mode to QIviAbstractFeature::AutoDiscovery means that the
feature implementation automatically finds and loads the corresponding backend or reports
an error. The application code only has to wait for the QIviAbstractFeature::isValid property
to become \c true.

As the front-end and backend of each feature is separated, the backends can be dynamically
exchanged. For instance, a single API can be provided to all media playback features of
the vehicle and then the backend is exchanged dynamically. This is done by modifying the
QIviAbstractFeature::serviceObject property. In these cases
QIviAbstractFeature::discoveryMode must be set to QIviAbstractFeature::NoAutoDiscovery to
prevent Qt IVI to automatically loading a backend.

\section2 Zones

Zones provide a standard way to provide a single API for multiple points in the vehicle.
For instance, climate control commonly has driver and passenger zones, and might even have
a rear seat zone. The same goes for wheels, doors, mirrors, windows and more.

A zoned feature provides a QIviAbstractZonedFeature::availableZones property holding the
names of the available zones. Notice that there are no zones until the \c isValid property
is \c true.

In C++, zones are accessed through the QIviAbstractZonedFeature::zoneAt() or through the
QIviAbstractZonedFeature::zones list.

In QML, the zones can be accessed through the AbstractZonedFeature::zoneAt property, for example, \c{climateControl.zoneAt.FrontSeat.seatheater}, or through the AbstractZonedFeature::zones
model. The model's \c modelData property exposes the API of the individual zones.

Zones with similar but slightly different configurations, e.g. there is no steering wheel
heater on the passenger side, commonly rely on
\l {Using the Qt IVI Reference API#property-attributes} {property attributes} to to
differentiate between the zones.

\section2 Property Attributes

Some properties are represented as QIviProperty instances instead of a plain old data
value type.

A QIviProperty has a \c value property, an \c availableValues list, a \c minimumValue
and \c maximumValue range pair, and an \c available flag.

The \c availableValues is only used for enums, while \c minimumValue and \c maximumValue are
used for numeric values. \c value and \c available are used for all properties.

Accessing a property where \c available is \c false will return an undefined value,
while trying to set an unavailable property has no effect.

*/