diff options
Diffstat (limited to 'src/CommonAPI')
-rw-r--r-- | src/CommonAPI/Attribute.h | 58 | ||||
-rw-r--r-- | src/CommonAPI/Event.h | 32 | ||||
-rw-r--r-- | src/CommonAPI/Factory.h | 127 | ||||
-rw-r--r-- | src/CommonAPI/Runtime.h | 33 | ||||
-rw-r--r-- | src/CommonAPI/SerializableVariant.h | 94 |
5 files changed, 340 insertions, 4 deletions
diff --git a/src/CommonAPI/Attribute.h b/src/CommonAPI/Attribute.h index a466e78..8295a3e 100644 --- a/src/CommonAPI/Attribute.h +++ b/src/CommonAPI/Attribute.h @@ -18,6 +18,11 @@ namespace CommonAPI { +/** + * \brief Class representing a read only attribute + * + * Class representing a read only attribute + */ template <typename _ValueType> class ReadonlyAttribute { public: @@ -26,10 +31,32 @@ class ReadonlyAttribute { 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. + * @return Call status of the operation. + */ virtual CallStatus getValue(_ValueType& value) 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) = 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: @@ -38,11 +65,35 @@ class Attribute: public ReadonlyAttribute<_ValueType> { 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) = 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) = 0; }; +/** + * \brief Class representing an observable attribute + * + * Class representing an observable attribute + */ template <typename _AttributeBaseClass> class _ObservableAttributeImpl: public _AttributeBaseClass { public: @@ -52,6 +103,13 @@ class _ObservableAttributeImpl: public _AttributeBaseClass { virtual ~_ObservableAttributeImpl() { } + /** + * \brief Returns the event handler for the remote change notifiaction event + * + * Returns the event handler for the remote change notifiaction event + * + * @return The event handler object + */ virtual ChangedEvent& getChangedEvent() = 0; }; diff --git a/src/CommonAPI/Event.h b/src/CommonAPI/Event.h index 956ea8d..6c7c1cf 100644 --- a/src/CommonAPI/Event.h +++ b/src/CommonAPI/Event.h @@ -19,7 +19,11 @@ enum class SubscriptionStatus { CANCEL }; - +/** + * \brief Class representing an event + * + * Class representing an event + */ template <typename... _Arguments> class Event { public: @@ -31,8 +35,34 @@ class Event { class CancellableListenerWrapper; + /** + * \brief Subscribe a listener to this event + * + * Subscribe a listener to this event + * + * @param listener A listener to be added + * @return A token identifying this subscription + */ inline Subscription subscribe(Listener listener); + + /** + * \brief Subscribe a cancellable listener to this event + * + * Subscribe a cancellable listener to this event + * + * @param listener A cancellable listener to be added + * @return A token identifying this subscription + */ Subscription subscribeCancellableListener(CancellableListener listener); + + /** + * \brief Remove a listener from this event + * + * Remove a listener from this event + * Note: Do not call this inside a listener notification callback it will deadlock! Use cancellable listeners instead. + * + * @param listenerSubscription A listener token to be removed + */ void unsubscribe(Subscription listenerSubscription); virtual ~Event() {} diff --git a/src/CommonAPI/Factory.h b/src/CommonAPI/Factory.h index 47dda82..7f167a1 100644 --- a/src/CommonAPI/Factory.h +++ b/src/CommonAPI/Factory.h @@ -35,9 +35,20 @@ struct DefaultAttributeProxyFactoryHelper; template<template<typename ...> class _ProxyClass, template<typename> class _AttributeExtension> std::shared_ptr<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t> createProxyWithDefaultAttributeExtension(Factory* specificFactory, const std::string& participantId, const std::string& domain); - +/** + * \brief The main CommonAPI access class. A factory is responsible for creation and destruction of service objects. + * + * The main CommonAPI access class. A factory is responsible for creation and destruction of service objects. + * This includes proxies and stubs. It also provides service discovery methods. + */ class Factory { public: + + /** + * \brief Creates factory. Don't call manually. + * + * Creates factory. Don't call manually. + */ Factory(const std::shared_ptr<Runtime> runtime, const MiddlewareInfo* middlewareInfo): runtime_(runtime), @@ -46,6 +57,17 @@ class Factory { virtual ~Factory() {} + /** + * \brief Build a proxy for the specified address + * + * Build a proxy for the specified address. + * Template this method call for the desired proxy type and attribute extension. + * + * @param participantId The participant ID of the common API address (last part) + * @param serviceName The service name of the common API address (middle part) + * @param domain The domain of the common API address (first part) + * @return a shared pointer to the constructed proxy + */ template<template<typename ...> class _ProxyClass, typename ... _AttributeExtensions> std::shared_ptr<_ProxyClass<_AttributeExtensions...> > buildProxy(const std::string& participantId, @@ -56,6 +78,15 @@ class Factory { return std::make_shared<_ProxyClass<_AttributeExtensions...>>(abstractMiddlewareProxy); } + /** + * \brief Build a proxy for the specified address + * + * Build a proxy for the specified address. + * Template this method call for the desired proxy type and attribute extension. + * + * @param serviceAddress The common API address + * @return a shared pointer to the constructed proxy + */ template<template<typename ...> class _ProxyClass, typename ... _AttributeExtensions > std::shared_ptr<_ProxyClass<_AttributeExtensions...> > buildProxy(const std::string& serviceAddress) { @@ -70,6 +101,17 @@ class Factory { return buildProxy<_ProxyClass, _AttributeExtensions...>(participantId, serviceName, domain); } + /** + * \brief Build a proxy for the specified address with one extension for all attributes + * + * Build a proxy for the specified address with one extension for all attributes + * Template this method call for the desired proxy type attribute extension. + * + * @param participantId The participant ID of the common API address (last part) + * @param serviceName The service name of the common API address (middle part) + * @param domain The domain of the common API address (first part) + * @return a shared pointer to the constructed proxy + */ template <template<typename ...> class _ProxyClass, template<typename> class _AttributeExtension> std::shared_ptr<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t> buildProxyWithDefaultAttributeExtension(const std::string& participantId, @@ -80,6 +122,15 @@ class Factory { return std::make_shared<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t>(abstractMiddlewareProxy); } + /** + * \brief Build a proxy for the specified address with one extension for all attributes + * + * Build a proxy for the specified address with one extension for all attributes + * Template this method call for the desired proxy type attribute extension. + * + * @param serviceAddress The common API address + * @return a shared pointer to the constructed proxy + */ template <template<typename ...> class _ProxyClass, template<typename> class _AttributeExtension> std::shared_ptr<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t> buildProxyWithDefaultAttributeExtension(const std::string& serviceAddress) { @@ -94,10 +145,28 @@ class Factory { return buildProxyWithDefaultAttributeExtension<_ProxyClass, _AttributeExtension>(participantId, serviceName, domain); } + /** + * \brief Get a pointer to the runtime of this factory. + * + * Get a pointer to the runtime of this factory. + * + * @return the Runtime + */ inline std::shared_ptr<Runtime> getRuntime() { return runtime_; } + /** + * \brief Register a service stub under a specified address + * + * Register a service stub under a specified address + * + * @param stub The stub pointer + * @param participantId The participant ID of the common API address (last part) + * @param serviceName The service name of the common API address (middle part) + * @param domain The domain of the common API address (first part) + * @return Was the registration successful + */ template<typename _Stub> bool registerService(std::shared_ptr<_Stub> stub, const std::string& participantId, @@ -108,6 +177,15 @@ class Factory { return registerAdapter(stubBase, _Stub::StubAdapterType::getInterfaceId(), participantId, serviceName, domain); } + /** + * \brief Register a service stub under a specified address + * + * Register a service stub under a specified address + * + * @param stub The stub pointer + * @param serviceAddress The common API address + * @return Was the registration successful + */ template<typename _Stub> bool registerService(std::shared_ptr<_Stub> stub, const std::string& serviceAddress) { std::string domain; @@ -120,7 +198,26 @@ class Factory { return registerService<_Stub>(stub, participantId, serviceName, domain); } + /** + * \brief Unregister a service stub associated with a specified address + * + * Unregister a service stub associated with a specified address + * + * @param participantId The participant ID of the common API address (last part) + * @param serviceName The service name of the common API address (middle part) + * @param domain The domain of the common API address (first part) + * @return Was the deregistration successful + */ virtual bool unregisterService(const std::string& participantId, const std::string& serviceName, const std::string& domain) = 0; + + /** + * \brief Unregister a service stub associated with a specified address + * + * Unregister a service stub associated with a specified address + * + * @param serviceAddress The common API address + * @return Was the deregistration successful + */ inline bool unregisterService(const std::string& serviceAddress) { std::string domain; std::string serviceName; @@ -131,9 +228,37 @@ class Factory { return unregisterService(participantId, serviceName, domain); } + /** + * \brief Get all instances of a specific service name available. Synchronous call. + * + * Get all instances of a specific service name available. Synchronous call. + * + * @param serviceName The service name of the common API address (middle part) + * @param serviceDomainName The domain of the common API address (first part) + * @return A vector of strings containing the available complete common api addresses. + */ virtual std::vector<std::string> getAvailableServiceInstances(const std::string& serviceName, const std::string& serviceDomainName = "local") = 0; + /** + * \brief Is a particular complete common api address available. Synchronous call. + * + * Is a particular complete common api address available. Synchronous call. + * + * @param serviceAddress The common API address + * @return Is alive + */ virtual bool isServiceInstanceAlive(const std::string& serviceAddress) = 0; + + /** + * \brief Is a particular complete common api address available. Synchronous call. + * + * Is a particular complete common api address available. Synchronous call. + * + * @param serviceInstanceID The participant ID of the common API address (last part) + * @param serviceName The service name of the common API address (middle part) + * @param serviceDomainName The domain of the common API address (first part) + * @return Is alive + */ virtual bool isServiceInstanceAlive(const std::string& serviceInstanceID, const std::string& serviceName, const std::string& serviceDomainName = "local") = 0; protected: diff --git a/src/CommonAPI/Runtime.h b/src/CommonAPI/Runtime.h index 92cf736..154cb67 100644 --- a/src/CommonAPI/Runtime.h +++ b/src/CommonAPI/Runtime.h @@ -26,14 +26,45 @@ namespace CommonAPI { class Factory; class Runtime; - +/** + * \brief Represents the CommonAPI runtime bindings available. + * + * Represents the CommonAPI runtime bindings available. + */ class Runtime { public: + + /** + * \brief Loads the default runtime + * + * Loads the default runtime. This is the only one available, or the default as defined in configuration + * + * @return The runtime object for this binding + */ static std::shared_ptr<Runtime> load(); + /** + * \brief Loads specified runtime + * + * Loads specified runtime. This is specified by either the well known name defined by the binding, or configured + * + * @return The runtime object for specified binding + */ static std::shared_ptr<Runtime> load(const std::string& middlewareId); + /** + * \brief Called by bindings to register their methods. Do not call from applications. + * + * Called by bindings to register their methods. Do not call from applications. + */ static void registerRuntimeLoader(std::string middlewareName, MiddlewareRuntimeLoadFunction middlewareRuntimeLoadFunction); virtual ~Runtime() {} + /** + * \brief Create a factory for the loaded runtime + * + * Create a factory for the loaded runtime + * + * @return Factory object for the loaded runtime + */ virtual std::shared_ptr<Factory> createFactory() = 0; }; diff --git a/src/CommonAPI/SerializableVariant.h b/src/CommonAPI/SerializableVariant.h index b7524ed..51f8224 100644 --- a/src/CommonAPI/SerializableVariant.h +++ b/src/CommonAPI/SerializableVariant.h @@ -25,6 +25,11 @@ class TypeOutputStream; template<typename _Type> struct TypeWriter; +/** + * \brief A variant class which can be serialised by bindings. + * + * A variant class which can be serialised by bindings. + */ class SerializableVariant { public: virtual ~SerializableVariant() { @@ -63,6 +68,11 @@ struct VariantTypeSelector<_SearchType, _SearchType, _RestTypes...> { typedef _SearchType type; }; +/** + * \brief A templated generic variant class which provides type safe access and operators + * + * A templated generic variant class which provides type safe access and operators + */ template<typename ... _Types> class Variant: public SerializableVariant { private: @@ -72,10 +82,30 @@ public: static const unsigned int maxSize = MaxSize<_Types...>::value; + /** + * \brief Construct an empty variant + * + * Construct an empty variant + */ Variant(); + + /** + * \brief Copy constructor. Must have identical templates. + * + * Copy constructor. Must have identical templates. + * + * @param fromVariant Variant to copy + */ Variant(const Variant& fromVariant); + /** + * \brief Copy constructor. Must have identical templates. + * + * Copy constructor. Must have identical templates. + * + * @param fromVariant Variant to copy + */ Variant(Variant&& fromVariant); ~Variant(); @@ -86,27 +116,82 @@ public: virtual void writeToTypeOutputStream(TypeOutputStream& typeOutputStream) const; + /** + * \brief Assignment of another variant. Must have identical templates. + * + * Assignment of another variant. Must have identical templates. + * + * @param rhs Variant to assign + */ Variant& operator=(const Variant& rhs); - + /** + * \brief Assignment of another variant. Must have identical templates. + * + * Assignment of another variant. Must have identical templates. + * + * @param rhs Variant to assign + */ Variant& operator=(Variant&& rhs); + /** + * \brief Assignment of a contained type. Must be one of the valid templated types. + * + * Assignment of a contained type. Must be one of the valid templated types. + * + * @param value Value to assign + */ template<typename _Type> typename std::enable_if<!std::is_same<_Type, Variant<_Types...>>::value, Variant<_Types...>&>::type operator=(const _Type& value); + /** + * \brief Equality of another variant. Must have identical template list and content. + * + * Equality of another variant. Must have identical template list and content. + * + * @param rhs Variant to compare + */ bool operator==(const Variant<_Types...>& rhs) const; + /** + * \brief Not-Equality of another variant. Must have identical template list and content. + * + * Not-Equality of another variant. Must have identical template list and content. + * + * @param rhs Variant to compare + */ bool operator!=(const Variant<_Types...>& rhs) const; + /** + * \brief Testif the contained type is the same as the template on this method. + * + * Testif the contained type is the same as the template on this method. + * + * @return Is same type + */ template <typename _Type> const bool isType() const; + /** + * \brief Construct variant with content type set to value. + * + * Construct variant with content type set to value. + * + * @param value Value to place + */ template <typename _Type> Variant(const _Type& value, typename std::enable_if<!std::is_const<_Type>::value>::type* = 0, typename std::enable_if<!std::is_reference<_Type>::value>::type* = 0, typename std::enable_if<!std::is_same<_Type, Variant>::value>::type* = 0); + /** + * \brief Construct variant with content type set to value. + * + * Construct variant with content type set to value. + * + * @param value Value to place + */ template <typename _Type> Variant(_Type && value, typename std::enable_if<!std::is_const<_Type>::value>::type* = 0, @@ -116,6 +201,13 @@ public: template <typename _Type> const _Type& get() const; + /** + * \brief Get index in template list of type actually contained + * + * Get index in template list of type actually contained + * + * @return Index of contained type + */ inline uint8_t getValueType() const { return valueType_; } |