CommonAPI C++(fidl)介绍

CommonAPI的基础部分

• 第一部分是由CommonAPI代码生成器生成的基于Franca的部分，也就是根据*.fidl文件生成的部分。那是接口的一部分，它是根据FrancaIDL文件中的规范生成的，指数据类型，数组，枚举和接口等基础知识，包含属性，方法，回调，错误处理，广播等方面。

• 第二个固定部分，是基于CommonAPIRuntime的功能，且独立于接口的规范。它们主要与基于中间件（someip/d-bus）提供的运行时环境有关。此外，此部分包含常见的类型定义和基类。也就是CommonAPI源代码库与所选中间件（someip/d-bus）的源代码库，供代码生成器生成的代码调用。

通用API运行时是从其开始所有类加载的基类。通用API运行时访问配置文件，以确定应加载哪个特定的中间件运行时库。中间件库是静态链接的，或者是作为共享库（文件扩展名.so）提供的，因此可用动态加载它们。

Franca 基础部分

fild文件的基本构成

类别1	类别2	说明	举例
package		限定包名，与命名空间（namespace）有关，必须包含	Package commonapi.examples
	interface	接口，提供一个接口名称，用于包含接口函数等，当定义接口时需要	Interface Methods
	version	版本号，同命名空间（namespace）有关，必须包含	version{major 0 minor 1}
	method	方法，定义供应用程序所调用的输入输出接口函数，具有in，out，error三种参数，这三种参数都是可选的，可以只有in和out，或只有in等多种组合。	method foo { in { Int32 x1 String x2 } out { Int32 y1 String y2} error{ stdErrorTypeEnum } }
	broadcast	广播，定义供应用程序调用的广播类接口函数；只有out参数。	broadcast myStatus { out { Int32 myCurrentValue } }
	attribute	属性，对各种属性进行定义，可用于获取或设置属性值	attribute Int32 x
	typedef	定义类型别名	typedef MyType is Int32
	array	数组	array myArray of UInt16
	enumeration	枚举类型	enumeration stdErrorTypeEnum { NO_FAULT MY_FAULT }
	union	联合类型	union MyUnion {UInt32 MyUIntString MyString}
	struct	结构体	struct a2Struct { Int32 a Boolean b Double d}
	map	一种STL关联容器，以一种键值-对的机制存储数据	map MyMap {UInt32 to String}
typeCollection		类型集合，用户根据自己的需要添加的数据类型的集合，各种数据结构在同一个文件中进行扩展等	typeCollection CommonTypes
	version	同interface::version	同interface::version
	typedef	同interface::typedef	同interface::typedef
	array	同interface::array	同interface::array
	enumeration	同interface::enumeration	同interface::enumeration
	union	同interface::union	同interface::union
	struct	同interface::struct	同interface::struct
	map	同interface::map	同interface::map

使用例子

/* Copyright (C) 2015 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

package commonapi.examples

interface E02Attributes {
    version { major 1 minor 0 }

    attribute Int32 x
    attribute CommonTypes.a1Struct a1
}

typeCollection CommonTypes {
    version { major 1 minor 0 }
    
    struct a1Struct {
        String s
        a2Struct a2
    }

    struct a2Struct {
        Int32 a
        Boolean b
        Double d
    }
}

语法讲解

命名空间

Common API基本函数的名称空间是Common API；

Common API应用程序的名称空间取决于Franca IDL中定义接口规范和接口版本的限定包名。

Franca IDL文件中显示：

生成的代码中显示（CommonAPI C++）：

namespace 每个文件的开头都有，代表这个文件所在的src-gen下面的路径，每个namespace代表一层目录；

如果接口没有版本，则省略名称空间中与版本有关的部分（例如图中的namespace v0）。

Version {major 1 minor 0} -- namespace v1 { }
Version {major 0 minor 1} -- namespace v0 { }
Version {major 0 minor 0} -- 无与版本相关的namespce

接口interface

Franca IDL文件中显示：

生成代码中的显示：

IDL文件中的版本号也会映射到代码中。

类型集合Type Collection

在Franca中，可以将一组用户定义的类型定义为type collection。

类型集合的名称称为typecollectionname，可以为空。CommonAPI为空类型集合使用默认名称Anonymous。CommonAPI代码生成器生成头文件Anonymous.hpp，并为类型集合创建C++ struct。

如果类型集合的名称不为空（例如：CommonTypes），则CommonAPI代码生成器生成头文件CommonTypes.hpp。

Franca IDL文件中显示：

生成代码中的显示：

方法Method

方法具有in和out参数，并且可以返回可选的应用程序错误error。

如果指定了附加标志fireAndForget，则不允许使用out参数，它指示既不返回值也不表示调用状态。没有fireAndForget标志的方可能返回error，可以在Franca IDL中将其指定为枚举。

对于没有fireAndForget标志的方法，提供了一个附加的返回值CallStatus，它被定义为枚举.

Franca IDL文件中显示：

在Franca IDL中，方法的异步或同步调用之间没有区别。

CommonAPI将同时提供两者。API的用户可以决定他调用哪个变体。含有fireAndForget标志的method，只有同步调用，没有异步调用。

广播Broadcast

广播只能有out参数。对于广播，可以定义一个附加标志selective。该标志指示该消息不应该发送给所有注册的参与者，而是该服务进行选择，表示只有选定的客户端才能在广播中注册。

Franca IDL文件中显示：

属性Attributes

接口的属性由名称和类型定义。另外，属性的规范可以具有两个标志：
·noSubscriptions
·readonly

标志	说明
none	没有附加任何标志的标准属性，默认允许所有内容
readonly	只读属性
noSubscriptions	不可观察的属性
readonly onSubscriptions	不可观察和不可写的属性

可观察的属性提供了一个ChangedEvent，可用于订阅对该属性的更新。此事件与所有其他事件完全一样。
头文件Attribute.h中定义了这四种类型的每种属性的模板类。

/**
 * \brief Class representing a read only attribute
 *
 * Class representing a read only attribute
 */
template <typename ValueType_>
class ReadonlyAttribute {
 public:
    typedef ValueType_ ValueType;

    typedef std::function<void(const CallStatus &, ValueType_)> AttributeAsyncCallback;

    virtual ~ReadonlyAttribute() { }

    /**
     * \brief Get value of attribute, usually from remote. Synchronous call.
     *
     * Get value of attribute, usually from remote. Synchronous call.
     *
     * @param value Reference to be filled with value.
     * @param callStatus call status reference will be filled with status of the operation
     */
    virtual void getValue(CallStatus &_status,
                          ValueType_ &_value,
                          const CallInfo *_info = nullptr) const = 0;

    /**
     * \brief Get value of attribute, usually from remote. Asynchronous call.
     *
     * Get value of attribute, usually from remote. Asynchronous call.
     *
     * @param attributeAsyncCallback std::function object for the callback to be invoked.
     * @return std::future containing the call status of the operation.
     */
    virtual std::future<CallStatus> getValueAsync(AttributeAsyncCallback attributeAsyncCallback,
                                                  const CallInfo *_info = nullptr) = 0;
};

/**
 * \brief Class representing a read and writable attribute
 *
 * Class representing a read and writable attribute
 */
template <typename ValueType_>
class Attribute: public ReadonlyAttribute<ValueType_> {
 public:
    typedef typename ReadonlyAttribute<ValueType_>::ValueType ValueType;
    typedef typename ReadonlyAttribute<ValueType_>::AttributeAsyncCallback AttributeAsyncCallback;

    virtual ~Attribute() { }

    /**
     * \brief Set value of attribute, usually to remote. Synchronous call.
     *
     * Set value of attribute, usually to remote. Synchronous call.
     *
     * @param requestValue Value to be set
     * @param callStatus call status reference will be filled with status of the operation
     * @param responseValue Reference which will contain the actuall value set by the remote.
     */
    virtual void setValue(const ValueType_& requestValue,
                          CallStatus& callStatus,
                          ValueType_& responseValue,
                          const CallInfo *_info = nullptr) = 0;

    /**
     * \brief Set value of attribute, usually to remote. Asynchronous call.
     *
     * Set value of attribute, usually to remote. Asynchronous call.
     *
     * @param requestValue Value to be set
     * @param attributeAsyncCallback std::function object for the callback to be invoked.
     * @return std::future containing the call status of the operation.
     */
    virtual std::future<CallStatus> setValueAsync(const ValueType_& requestValue,
                                                  AttributeAsyncCallback attributeAsyncCallback,
                                                  const CallInfo *_info = nullptr) = 0;
};

/**
 * \brief Class representing an observable attribute
 *
 * Class representing an observable attribute
 */
template <typename AttributeBaseClass_>
class ObservableAttributeImpl: public AttributeBaseClass_ {
 public:
    typedef typename AttributeBaseClass_::ValueType ValueType;
    typedef typename AttributeBaseClass_::AttributeAsyncCallback AttributeAsyncCallback;
    typedef Event<ValueType> ChangedEvent;

    virtual ~ObservableAttributeImpl() { }

    /**
     * \brief Returns the event handler for the remote change notification event
     *
     * Returns the event handler for the remote change notification event
     *
     * @return The event handler object
     */
    virtual ChangedEvent& getChangedEvent() = 0;
};

template <typename ValueType_>
struct ObservableReadonlyAttribute: ObservableAttributeImpl< ReadonlyAttribute<ValueType_> > {
};

template <typename ValueType_>
struct ObservableAttribute: ObservableAttributeImpl< Attribute<ValueType_> > {
};

Franca IDL文件中显示：

事件events

事件为远程触发的动作提供了一个异步接口。

这涵盖了FrancaIDL中的广播，方法和属性的更改，事件每个proxy还提供了一个可用性事件，可用于通知proxy状态。事件提供了订阅和取消订阅的方法，该方法允许注册和注销回调。

事件类的公共接口的相关部分如下：

数据类型

基本类型
CommonAPI使用的整数数据类型在stdint.h中定义。

Franca	Type Name	CommonAPI C++ Type Notes
UInt8	uint8_t	unsigned 8-bit integer(range 0…255)
Int8	int8_t	signed 8-bit integer(range -128…127)
UInt16	uint16_t	unsigned 16-bit integer(range 0…65535)
Int16	int16_t	signed 16-bit integer(range -32768…32767)
UInt32	uint32_t	unsigned 32-bit integer(range 0…4294967295)
Int32	int32_t	signed 32-bit integer(range -2147483648…2147473647)
UInt64	uint64_t	unsigned 64-bit integer
Int64	int64_t	signed 64-bit integer
Boolean	bool	boolean value, which can take one of two values: false or true
Float	float	Floating point number(4 bytes, range +/3.4e+/-38, ~7 digits).
Double	double	double precision floating point number(8 bytes, range+/-1.7e+/-308, ~15 digits).
String	std::string	character string.
ByteBuffer	std::vector<uint8_t>	buffer of bytes(aka BLOB).