image.png
CommonAPI的基础部分
image.png
-
第一部分是由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文件中显示：
image.png
生成的代码中显示（CommonAPI C++）：
image.png
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文件中显示：
image.png
生成代码中的显示：
image.png
IDL文件中的版本号也会映射到代码中。
类型集合Type Collection
在Franca中，可以将一组用户定义的类型定义为type collection。
类型集合的名称称为typecollectionname，可以为空。CommonAPI为空类型集合使用默认名称Anonymous。CommonAPI代码生成器生成头文件Anonymous.hpp，并为类型集合创建C++ struct。
如果类型集合的名称不为空（例如：CommonTypes），则CommonAPI代码生成器生成头文件CommonTypes.hpp。
Franca IDL文件中显示：
image.png
生成代码中的显示：
image.png
方法Method
方法具有in和out参数，并且可以返回可选的应用程序错误error。
如果指定了附加标志fireAndForget，则不允许使用out参数，它指示既不返回值也不表示调用状态。没有fireAndForget标志的方可能返回error，可以在Franca IDL中将其指定为枚举。
对于没有fireAndForget标志的方法，提供了一个附加的返回值CallStatus，它被定义为枚举.
Franca IDL文件中显示：
image.png
在Franca IDL中，方法的异步或同步调用之间没有区别。
CommonAPI将同时提供两者。API的用户可以决定他调用哪个变体。含有fireAndForget标志的method，只有同步调用，没有异步调用。
image.png
广播Broadcast
广播只能有out参数。对于广播，可以定义一个附加标志selective。该标志指示该消息不应该发送给所有注册的参与者，而是该服务进行选择，表示只有选定的客户端才能在广播中注册。
Franca IDL文件中显示：
image.png
属性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文件中显示：
image.png
事件events
事件为远程触发的动作提供了一个异步接口。
这涵盖了FrancaIDL中的广播，方法和属性的更改，事件每个proxy还提供了一个可用性事件，可用于通知proxy状态。事件提供了订阅和取消订阅的方法，该方法允许注册和注销回调。
事件类的公共接口的相关部分如下：
image.png
数据类型
基本类型
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). |
网友评论