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