diff options
Diffstat (limited to 'interface/vsomeip/application.hpp')
-rw-r--r-- | interface/vsomeip/application.hpp | 954 |
1 files changed, 954 insertions, 0 deletions
diff --git a/interface/vsomeip/application.hpp b/interface/vsomeip/application.hpp new file mode 100644 index 0000000..42bd534 --- /dev/null +++ b/interface/vsomeip/application.hpp @@ -0,0 +1,954 @@ +// Copyright (C) 2014-2017 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/. + +#ifndef VSOMEIP_APPLICATION_HPP +#define VSOMEIP_APPLICATION_HPP + +#include <chrono> +#include <memory> +#include <set> +#include <map> +#include <vector> + +#include <vsomeip/primitive_types.hpp> +#include <vsomeip/enumeration_types.hpp> +#include <vsomeip/function_types.hpp> +#include <vsomeip/constants.hpp> +#include <vsomeip/handler.hpp> + +namespace vsomeip { + +class configuration; +class event; +class payload; + +/** + * \defgroup vsomeip + * + * @{ + */ + +/** + * + * \brief This class contains the public API of the vsomeip implementation. + * + * Due to its heavy resource footprint, it should exist once per client and can + * be instantiated using the API of @ref runtime. It manages the lifecycle of + * the vsomeip client and allocates all resources needed to communicate. + * + */ +class application { +public: + virtual ~application() {} + + /** + * + * \brief Returns the name of the application as given during creation + * + * The application name is used to identify the application. It is either + * set explicitely when the application object is created or configured by + * the environment variable VSOMEIP_APPLICATION_NAME. + * + * Note: A user application can use several vsomeip application objects in + * parallel. The application names must be set explicitly in this case + * because VSOMEIP_APPLICATION_NAME only allows to specify a single name. + * + * + * \return Application name + * + */ + virtual const std::string & get_name() const = 0; + + /** + * + * \brief Returns the client identifier that was assigned to the + * application object. + * + * Each request sent by and each response sent to the application contain + * the client identifier as part of the request identifier within the + * SOME/IP message header. The client identifier can either be configured + * by the configured as part of the application node within a vsomeip + * configuration file or is automatically set to an unused client + * identifier by vsomeip. If the client identifier is automatically set, + * its high byte will always match the diagnosis address of the device. + * + * \return Client ID of application + * + */ + virtual client_t get_client() const = 0; + + /** + * + * \brief Does nothing. + * + * This method exists for compatibility reasons only. It is a null + * operation and will be removed with the next major vsomeip version. + * + */ + virtual void set_configuration(const std::shared_ptr<configuration> _configuration) = 0; + + /** + * + * \brief Initializes the application. + * + * The init method must be called first after creating a vsomeip + * application and executes the following steps to initialize it: + * - Loading the configuration from a dynamic module + * - Loading the configuration from a .json file or + * - Loading the configuration from compiled data (not yet available) + * - Determining routing configuration and initialization of the routing + * itself + * - Installing signal handlers + * + */ + virtual bool init() = 0; + + /** + * + * \brief Starts message processing. + * + * This method must be called after init to start message processing. It + * will block until the message processing is terminated using the @ref + * stop method or by receiving signals. It processes messages received + * via the sockets and uses registered callbacks to pass them to the user + * application. + * + */ + virtual void start() = 0; + + /** + * + * \brief Stops message processing. + * + * This method stops message processing. Thus, @ref start will return + * after a call to stop. + * + */ + virtual void stop() = 0; + + /** + * + * \brief Offers a SOME/IP service instance. + * + * The user application must call this method for each service it offers + * to register it at the vsomeip routing component, which makes the + * service visible to interested clients. Dependent on the configuration + * the service is available internally only or internally and externally. + * To offer a service to the external network, the configuration must + * contain a port for the offered service instance. If no such port + * configuration is provided, the service is not visible outside the + * device. + * + * \param _service Service identifier of the offered service interface. + * \param _instance Instance identifier of the offered service instance. + * \param _major Major service version (Default: 0). + * \param _minor Minor service version (Default: 0). + * + */ + virtual void offer_service(service_t _service, instance_t _instance, + major_version_t _major = DEFAULT_MAJOR, minor_version_t _minor = + DEFAULT_MINOR) = 0; + + /** + * + * \brief Stops offering a SOME/IP service instance. + * + * The user application must call this method to withdraw a service offer. + * + * \param _service Service identifier of the offered service interface. + * \param _instance Instance identifer of the offered service instance. + * \param _major Major service version (Default: 0). + * \param _minor Minor service version (Default: 0). + * + */ + virtual void stop_offer_service(service_t _service, instance_t _instance, + major_version_t _major = DEFAULT_MAJOR, minor_version_t _minor = + DEFAULT_MINOR) = 0; + + /** + * + * \brief Offers a SOME/IP event or field. + * + * A user application must call this method for each event/field it wants + * to offer. The event is registered at the vsomeip routing component that + * enables other applications to subscribe to the event/field as well as + * to get and set the field value. + * + * \param _service Service identifier of the interface containing the + * event. + * \param _instance Instance identifier of the interface containing the + * event. + * \param _event Event identifier of the offered event. + * \param _eventgroups List of eventgroup identifiers of the eventgroups + * that contain the event. + * \param _is_field Selector for event or field. + * + */ + virtual void offer_event(service_t _service, + instance_t _instance, event_t _event, + const std::set<eventgroup_t> &_eventgroups, + bool _is_field) = 0; + + /** + * + * \brief Stops offering a SOME/IP event or field. + * + * A user application must call this method to withdraw the offer of an + * event or field. + * + * \param _service Service identifier of the interface that contains the + * event + * \param _instance Instance identifier of the interface that contains the + * event + * \param _event Event identifier of the offered event. + * + */ + virtual void stop_offer_event(service_t _service, + instance_t _instance, event_t _event) = 0; + + /** + * + * \brief Registers the application as client of a service instance. + * + * A user application must call this method for each service instance it + * wants to use. The request is stored within the routing component and the + * application is registered as client for the service as soon as the + * service instance becomes available. + * + * \param _service Service identifier of the requested service interface. + * \param _instance Instance identifier of the requested service instance. + * \param _major Major service version (Default: 0xFF). + * \param _minor Minor service version (Default: 0xFFFFFF). + * \param _use_exclusive_proxy Create an IP endpoint that is exclusively + * used for the communication of this application to the service instance. + * + */ + virtual void request_service(service_t _service, instance_t _instance, + major_version_t _major = ANY_MAJOR, + minor_version_t _minor = ANY_MINOR, + bool _use_exclusive_proxy = false) = 0; + + /** + * + * \brief Unregister the application as client of a service instance. + * + * A user application should call this method if it does not request to + * use the service instance any longer. The method unregisters the request + * a the routing component, which removes the service instance from the + * list of requested service instances if the call releases the last + * existing request for the service instance. This is important for + * external service instances, as the SOME/IP Service Discovery can avoid + * to send unnecessary Find messages. + * + * \param _service Service identifier of the offered service interface. + * \param _instance Instance identifier of the offered service instance. + * + */ + virtual void release_service(service_t _service, instance_t _instance) = 0; + + /** + * + * \brief Registers the application as user of an event or field. + * + * A user application must call this method before being able to receive + * event or field data. The method registers the event or field at the + * routing component. + * + * \param _service Service identifier of the interface that contains the + * event. + * \param _instance Instance identifier of the interface that contains the + * event. + * \param _event Event identifier of the event. + * \param _eventgroups List of Eventgroup identifiers of the eventgroups + * that contain the event. + * \param _is_field Pure event (false) or field (true). + * + */ + virtual void request_event(service_t _service, instance_t _instance, + event_t _event, const std::set<eventgroup_t> &_eventgroups, + bool _is_field) = 0; + /** + * + * \brief Unregister the application as user of an event or field. + * + * Unregister the application as user of an event or field and completely + * removes the event/field if the application is the last existing user. + * + * \param _service Service identifier of the interface that contains the + * event or field. + * \param _instance Instance identifier of the instance that contains the + * event or field. + * \param _event Event identifier of the event or field. + * . + */ + virtual void release_event(service_t _service, instance_t _instance, + event_t _event) = 0; + + /** + * + * \brief Subscribes to an eventgroup. + * + * A user application must call this function to subscribe to an eventgroup. + * Before calling subscribe it must register all events it interested in by + * calls to @ref request_event. The method additionally allows to specify + * a specific event. If a specific event is specified, all other events of + * the eventgroup are not received by the application. + * + * Note: For external services, providing a specific event does not change + * anything regarding the message routing. The specific event is only used + * to filter incoming events and to determine which initial events must be + * sent. + * + * \param _service Service identifier of the service that contains the + * eventgroup. + * \param _instance Instance identifier of the service that contains the + * eventgroup. + * \param _eventgroup Eventgroup identifier of the eventgroup. + * \param _major Major version number of the service. + * \param _subscription_type Specifies how the events shall be received. + * \param _event All (Default) or a specific event. + * + */ + virtual void subscribe(service_t _service, instance_t _instance, + eventgroup_t _eventgroup, major_version_t _major = DEFAULT_MAJOR, + subscription_type_e _subscription_type = subscription_type_e::SU_RELIABLE_AND_UNRELIABLE, + event_t _event = ANY_EVENT) = 0; + + /** + * + * \brief Unsubscribes from an eventgroup. + * + * \param _service Service identifier of the service that contains the + * eventgroup. + * \param _instance Instance identifier of the service that contains the + * eventgroup. + * \param _eventgroup Eventgroup identifier of the eventgroup. + * + */ + virtual void unsubscribe(service_t _service, instance_t _instance, + eventgroup_t _eventgroup) = 0; + + /** + * + * \brief Retrieve for the availability of a service instance. + * + * If the version is also given, the result will only be true if the + * service instance is available in that specific version. + * + * \param _service Service identifier of the service instance. + * \param _instance Instance identifier of the service instance. + * \param _major Major interface version. Use ANY_MAJOR to ignore the + * major version. + * \param _minor Minor interface version. Use ANY_MINOR to ignore the + * minor version. + * + */ + virtual bool is_available(service_t _service, instance_t _instance, + major_version_t _major = DEFAULT_MAJOR, minor_version_t _minor = DEFAULT_MINOR) const = 0; + + /** + * + * \brief Sends a message. + * + * Serializes the specified message object, determines the taget and sends + * the message to the target. For requests, the request identifier is + * automatically built from the client identifier and the session + * identifier. + * + * \param _message Message object. + * \param _flush If set to true, the message is immediately sent. Otherwise + * the message might be deferred and sent together with other messages. + * + */ + virtual void send(std::shared_ptr<message> _message, bool _flush = true) = 0; + + /** + * + * \brief Fire an event or field notification. + * + * The specified event is updated with the specified payload data. + * Dependent on the type of the event, the payload is distributed to all + * notified clients (always for events, only if the payload has changed + * for fields). + * + * Note: Prior to using this method, @ref offer_event has to be called by + * the service provider. + * + * \param _service Service identifier of the service that contains the + * event. + * \param _instance Instance identifier of the service instance that + * holds the event. + * \param _event Event identifier of the event. + * \param _payload Serialized payload of the event. + * + */ + virtual void notify(service_t _service, instance_t _instance, + event_t _event, std::shared_ptr<payload> _payload) const = 0; + + /** + * + * \brief Fire an event to a specific client. + * + * The specified event is updated with the specified payload data. + * Dependent on the type of the event, the payload is distributed to all + * notified clients (always for events, only if the payload has changed + * for fields). + * + * Note: Prior to using this method, @ref offer_event has to be called by + * the service provider. + * + * \param _service Service identifier of the service that contains the + * event. + * \param _instance Instance identifier of the service instance that + * holds the event. + * \param _event Event identifier of the event. + * \param _payload Serialized payload of the event. + * \param _client Target client. + * + */ + virtual void notify_one(service_t _service, instance_t _instance, + event_t _event, std::shared_ptr<payload> _payload, + client_t _client) const = 0; + + /** + * + * \brief Register a state handler with the vsomeip runtime. + * + * The state handler tells if this client is successfully [de]registered + * at the central vsomeip routing component. This is called during the + * @ref start and @ref stop methods of this class to inform the user + * application about the registration state. + * + * \param _handler Handler function to be called on state change. + * + */ + virtual void register_state_handler(state_handler_t _handler) = 0; + + /** + * + * \brief Unregister the state handler. + * + */ + virtual void unregister_state_handler() = 0; + + /** + * + * \brief Registers a handler for the specified method or event. + * + * A user application must call this method to register callbacks for + * for messages that match the specified service, instance, method/event + * pattern. It is possible to specify wildcard values for all three + * identifiers arguments. + * + * Notes: + * - Only a single handler can be registered per service, instance, + * method/event combination. + * - A subsequent call will overwrite an existing registration. + * - Handler registrations containing wildcards can be active in parallel + * to handler registrations for specific service, instance, method/event + * combinations. + * + * \param _service Service identifier of the service that contains the + * method or event. Can be set to ANY_SERVICE to register a handler for + * a message independent from a specific service. + * \param _instance Instance identifier of the service instance that + * contains the method or event. Can be set to ANY_INSTANCE to register + * a handler for a message independent from a specific service. + * \param _method Method/Event identifier of the method/event that is + * to be handled. Can be set to ANY_METHOD to register a handler for + * all methods and events. + * \param _handler Callback that will be called if a message arrives + * that matches the specified service, instance and method/event + * parameters. + * + */ + virtual void register_message_handler(service_t _service, + instance_t _instance, method_t _method, + message_handler_t _handler) = 0; + /** + * + * \brief Unregisters the message handler for the specified service + * method/event notification. + * + * \param _service Service identifier of the service that contains the + * method or event. Can be set to ANY_SERVICE to unregister a handler for + * a message independent from a specific service. + * \param _instance Instance identifier of the service instance that + * contains the method or event. Can be set to ANY_INSTANCE to unregister + * a handler for a message independent from a specific service. + * \param _method Method/Event identifier of the method/event that is + * to be handled. Can be set to ANY_METHOD to unregister a handler for + * all methods and events. + */ + virtual void unregister_message_handler(service_t _service, + instance_t _instance, method_t _method) = 0; + + /** + * + * \brief Register a callback that is called when service instances + * availability changes. + * + * This method allows for the registration of callbacks that are called + * whenever a service appears or disappears. It is possible to specify + * wildcards for service, instance and/or version. Additionally, the + * version specification is optional and defaults to DEFAULT_MAJOR + * /DEFAULT_MINOR. + * + * \param _service Service identifier of the service instance whose + * availability shall be reported. Can be set to ANY_SERVICE. + * \param _instance Instance identifier of the service instance whose + * availability shall be reported. Can be set to ANY_INSTANCE. + * \param _handler Callback to be called if availability changes. + * \param _major Major service version. The parameter defaults to + * DEFAULT_MAJOR and can be set to ANY_MAJOR. + * \param _minor Minor service version. The parameter defaults to + * DEFAULT_MINOR and can be set to ANY_MINOR. + * + */ + virtual void register_availability_handler(service_t _service, + instance_t _instance, availability_handler_t _handler, + major_version_t _major = DEFAULT_MAJOR, minor_version_t _minor = DEFAULT_MINOR) = 0; + + /** + * + * \brief Unregister an availability callback. + * + * \param _service Service identifier of the service instance whose + * availability shall be reported. Can be set to ANY_SERVICE. + * \param _instance Instance identifier of the service instance whose + * availability shall be reported. Can be set to ANY_INSTANCE. + * \param _handler Callback to be called if availability changes. + * \param _major Major service version. The parameter defaults to + * DEFAULT_MAJOR and can be set to ANY_MAJOR. + * \param _minor Minor service version. The parameter defaults to + * DEFAULT_MINOR and can be set to ANY_MINOR. * + */ + virtual void unregister_availability_handler(service_t _service, + instance_t _instance, + major_version_t _major = DEFAULT_MAJOR, minor_version_t _minor = DEFAULT_MINOR) = 0; + + /** + * + * \brief Registers a subscription handler. + * + * A subscription handler is called whenever the subscription state of an + * eventgroup changes. The callback is called with the client identifier + * and a boolean that indicates whether the client subscribed or + * unsubscribed. + * + * \param _service Service identifier of service instance whose + * subscription state is to be monitored. + * \param _instance Instance identifier of service instance whose + * subscription state is to be monitored. + * \param _eventgroup Eventgroup identifier of eventgroup whose + * subscription state is to be monitored. + * \param _handler Callback that shall be called. + * + */ + virtual void register_subscription_handler(service_t _service, + instance_t _instance, eventgroup_t _eventgroup, + subscription_handler_t _handler) = 0; + + /** + * + * \brief Unregister a subscription handler. + * + * \param _service Service identifier of service instance whose + * subscription state is to be monitored. + * \param _instance Instance identifier of service instance whose + * subscription state is to be monitored. + * \param _eventgroup Eventgroup identifier of eventgroup whose + * subscription state is to be monitored. + * + */ + virtual void unregister_subscription_handler(service_t _service, + instance_t _instance, eventgroup_t _eventgroup) = 0; + + // [Un]Register handler for subscription errors + /** + * + * \brief Allows for the registration of a subscription error handler. + * + * This handler is called whenever a subscription request for an eventgroup + * was either accepted or rejected. The respective callback is called with + * ether OK (0x00) or REJECTED (0x07). + * + * \param _service Service identifier of service instance whose + * subscription error state is to be monitored. + * \param _instance Instance identifier of service instance whose + * subscription error state is to be monitored. + * \param _eventgroup Eventgroup identifier of eventgroup whose + * subscription error state is to be monitored. + * \param _handler Callback that shall be called. + * + */ + virtual void register_subscription_error_handler(service_t _service, + instance_t _instance, eventgroup_t _eventgroup, + error_handler_t _handler) = 0; + + /** + * + * \brief Removes a registered subscription error callback. + * + * \param _service Service identifier of service instance whose + * error callback shall be removed. + * \param _instance Instance identifier of service instance whose + * error callback shall be removed. + * \param _eventgroup Eventgroup identifier of eventgroup whose + * error callback shall be removed. + * + */ + virtual void unregister_subscription_error_handler(service_t _service, + instance_t _instance, eventgroup_t _eventgroup) = 0; + + /** + * + * \brief Unregister all registered handlers. + * + */ + virtual void clear_all_handler() = 0; + + /** + * + * \brief This method tells whether or not this application controls the + * message routing. + * + * The application that controls the routing hosts the routing manager + * and (optionally) loads the Service Discovery component. + * + * \return true, if this is the central routing instance, and false + * otherwise + * + */ + virtual bool is_routing() const = 0; + + /** + * + * \brief Offers a SOME/IP event or field. + * + * A user application must call this method for each event/field it wants + * to offer. The event is registered at the vsomeip routing component that + * enables other applications to subscribe to the event/field as well as + * to get and set the field value. + * + * This version of offer_event adds some additional functionalities: + * - It is possible to configure a cycle time. The notification message of + * this event is then resent cyclically. + * - The parameter _change_resets_cycle is available to control how event + * notification works in case the data is updated by the application. If + * set to true, an update of the data immediately leads to a + * notification. Otherwise, the updated data is sent only after the + * expiration of the cycle time. + * - It is possible to specify callback function that can be used to + * implement a predicate that determines whether or not two event values + * are considered different. Field notifications are only sent if the + * predicate evaluates to true (or if a notify method is called with the + * force flag being set). + * + * \param _service Service identifier of the interface containing the + * event. + * \param _instance Instance identifier of the interface containing the + * event. + * \param _event Event identifier of the offered event. + * \param _eventgroups List of eventgroup identifiers of the eventgroups + * that contain the event. + * \param _is_field Selector for event or field. + * \param _cycle Sets the cycle time of the event. If nonzero, data is + * resent cyclically after the cycle time expired. + * \param _change_resets_cycle Tells if a change immediately leads to + * a notification. + * \param _epsilon_change_func Predicate that determines if two given + * payloads are considered different. + * + * Note: The different versions of offer_event exist for compatibility + * reasons. They will be merged with the next major vsomeip version. + */ + virtual void offer_event(service_t _service, + instance_t _instance, event_t _event, + const std::set<eventgroup_t> &_eventgroups, + bool _is_field, + std::chrono::milliseconds _cycle, + bool _change_resets_cycle, + const epsilon_change_func_t &_epsilon_change_func) = 0; + + /** + * + * \brief Fire an event or field notification. + * + * The specified event is updated with the specified payload data. + * Dependent on the type of the event, the payload is distributed to all + * notified clients (always for events, only if the payload has changed + * for fields). + * + * Note: Prior to using this method, @ref offer_event has to be called by + * the service provider. + * + * \param _service Service identifier of the service that contains the + * event. + * \param _instance Instance identifier of the service instance that + * holds the event. + * \param _event Event identifier of the event. + * \param _payload Serialized payload of the event. + * \param _force Forces the notification to be sent (even if the event + * is a field and the value did not change). + * + * Note: The different versions of notify do exist for compatibility + * reasons. They will be merged with the next major vsomeip release. + */ + virtual void notify(service_t _service, instance_t _instance, + event_t _event, std::shared_ptr<payload> _payload, + bool _force) const = 0; + + /** + * + * \brief Fire an event or field notification. + * + * The specified event is updated with the specified payload data. + * Dependent on the type of the event, the payload is distributed to all + * notified clients (always for events, only if the payload has changed + * for fields). + * + * Note: Prior to using this method, @ref offer_event has to be called by + * the service provider. + * + * \param _service Service identifier of the service that contains the + * event. + * \param _instance Instance identifier of the service instance that + * holds the event. + * \param _event Event identifier of the event. + * \param _payload Serialized payload of the event. + * \param _client Target client. + * \param _force Forces the notification to be sent (even if the event + * is a field and the value did not change). + * + * Note: The different versions of notify_one do exist for compatibility + * reasons. They will be merged with the next major vsomeip release. + */ + virtual void notify_one(service_t _service, instance_t _instance, + event_t _event, std::shared_ptr<payload> _payload, + client_t _client, bool _force) const = 0; + + typedef std::map<service_t, std::map<instance_t, std::map<major_version_t, minor_version_t >>> available_t; + /** + * \brief Returns all available instances that match the given combination + * of service, instance and version. + * + * This method checks the availability of the service instances that + * match the specified combination of service, instance and version + * parameters. If at least one matching service instance is available, + * the method returns true, otherwise it returns false. All available + * service instances are returned to the caller by filling the + * _available parameter. + * + * \param _available Map that is filled with the available instances. + * \param _service Service identifier that specifies which service(s) + * are checked. + * \param _instance Instance identifier that specifies which instance(s) + * are checked. + * \param _major_version Major version(s) of the service instances that + * are checked + * \param _minor_version Minor version(s) of the service instance that + * are checked + */ + virtual bool are_available(available_t &_available, + service_t _service = ANY_SERVICE, instance_t _instance = ANY_INSTANCE, + major_version_t _major = ANY_MAJOR, minor_version_t _minor = ANY_MINOR) const = 0; + + /** + * + * \brief Fire an event or field notification. + * + * The specified event is updated with the specified payload data. + * Dependent on the type of the event, the payload is distributed to all + * notified clients (always for events, only if the payload has changed + * for fields). + * + * Note: Prior to using this method, @ref offer_event has to be called by + * the service provider. + * + * \param _service Service identifier of the service that contains the + * event. + * \param _instance Instance identifier of the service instance that + * holds the event. + * \param _event Event identifier of the event. + * \param _payload Serialized payload of the event. + * \param _force Forces the notification to be sent (even if the event + * is a field and the value did not change). + * \param _flush Must be set to ensure the event is immediately fired. + * + * Note: The different versions of notify do exist for compatibility + * reasons. They will be merged with the next major vsomeip release. + */ + virtual void notify(service_t _service, instance_t _instance, + event_t _event, std::shared_ptr<payload> _payload, + bool _force, bool _flush) const = 0; + + /** + * + * \brief Fire an event or field notification. + * + * The specified event is updated with the specified payload data. + * Dependent on the type of the event, the payload is distributed to all + * notified clients (always for events, only if the payload has changed + * for fields). + * + * Note: Prior to using this method, @ref offer_event has to be called by + * the service provider. + * + * \param _service Service identifier of the service that contains the + * event. + * \param _instance Instance identifier of the service instance that + * holds the event. + * \param _event Event identifier of the event. + * \param _payload Serialized payload of the event. + * \param _client Target client. + * \param _force Forces the notification to be sent (even if the event + * is a field and the value did not change). + * \param _flush Must be set to ensure the event is immediately fired. + * + * Note: The different versions of notify_one do exist for compatibility + * reasons. They will be merged with the next major vsomeip release. + */ + virtual void notify_one(service_t _service, instance_t _instance, + event_t _event, std::shared_ptr<payload> _payload, + client_t _client, bool _force, bool _flush) const = 0; + + /** + * \brief Set the current routing state. + * + * The routing state impacts the behavior of the SOME/IP Service Discovery component. It + * can be set to RUNNING, SUSPENDED, RESUMED, SHUTDOWN or UNKNOWN. Applications only need + * to set the routing state if they are responsible for controlling the routing manager. + * In most environments the vsomeip daemon is controlling the routing manager. + * + * \param _routing_state the current routing state + */ + virtual void set_routing_state(routing_state_e _routing_state) = 0; + + /** + * + * \brief Unsubscribes from an eventgroup. + * + * \param _service Service identifier of the service that contains the + * eventgroup. + * \param _instance Instance identifier of the service that contains the + * eventgroup. + * \param _eventgroup Eventgroup identifier of the eventgroup. + * \param _event Event to unsubscribe (pass ANY_EVENT for all events of the eventgroup) + */ + virtual void unsubscribe(service_t _service, instance_t _instance, + eventgroup_t _eventgroup, event_t _event) = 0; + + + /** + * + * \brief Registers a subscription status listener. + * + * When registered such a handler it will be called for + * every application::subscribe call. + * + * This method is intended to replace the application:: + * register_subscription_error_handler call in future releases. + * + * \param _service Service identifier of the service that is subscribed to. + * \param _instance Instance identifier of the service that is subscribed to. + * \param _eventgroup Eventgroup identifier of the eventgroup is subscribed to. + * \param _event Event indentifier of the event is subscribed to. + * \param _handler A subscription status handler which will be called by vSomeIP + * as a follow of application::subscribe. + */ + virtual void register_subscription_status_handler(service_t _service, + instance_t _instance, eventgroup_t _eventgroup, event_t _event, + subscription_status_handler_t _handler) = 0; + + /** + * + * \brief Registers a subscription status listener. + * + * When registered such a handler it will be called for + * every application::subscribe call. + * + * This method is intended to replace the application:: + * register_subscription_error_handler call in future releases. + * + * \param _service Service identifier of the service that is subscribed to. + * \param _instance Instance identifier of the service that is subscribed to. + * \param _eventgroup Eventgroup identifier of the eventgroup is subscribed to. + * \param _event Event indentifier of the event is subscribed to. + * \param _handler A subscription status handler which will be called by vSomeIP + * as a follow of application::subscribe. + * \param _is_selective Flag to enable calling the provided handler if the + * subscription is answered with a SUBSCRIBE_NACK. + */ + virtual void register_subscription_status_handler(service_t _service, + instance_t _instance, eventgroup_t _eventgroup, event_t _event, + subscription_status_handler_t _handler, bool _is_selective) = 0; + + /** + * + * \brief Returns all registered services / instances on this node in an async callback. + * + * When called with a handler of type offered_services_handler_t, + * all at the routing manager registered services on this node get returned in a vector of + * service / instance pairs depending on the given _offer_type. + * + * \param _offer_type type of offered services to be returned (OT_LOCAL = 0x00, OT_REMOTE = 0x01, OT_ALL = 0x02) + * \param offered_services_handler_t handler which gets called with a vector of service instance pairs that are currently offered + */ + virtual void get_offered_services_async(offer_type_e _offer_type, offered_services_handler_t _handler) = 0; + + /** + * + * \brief Sets a handler to be called cyclically for watchdog monitoring. + * + * The handler shall be called in the given interval, but not before start() + * has been called, and not after call to stop() returned. + * + * In case the application is running, i.e. start() succeeded, but the + * handler will not be invoke within the (approximate) interval it may + * be assumed that I/O or internal dispatcher threads are non-functional. + * + * \remark Accuracy of call interval is limited by clock/timer granularity + * or scheduling effects, thus it may underrun or overrun by small + * amount. + * + * \note Only one handler can be active at the time, thus last handler set + * by calling this function will be invoked. + * + * \note To disable calling an active handler, invoke this method again, + * passing nullptr as _handler and/or std::chrono::seconds::zero() + * as _interval. + * + * \param _handler A watchdog handler, pass nullptr to deactivate. + * \param _interval Call interval in seconds, pass std::chrono::seconds::zero() to deactivate. + */ + virtual void set_watchdog_handler(watchdog_handler_t _handler, std::chrono::seconds _interval) = 0; + + /** + * + * \brief Registers a subscription handler. + * + * A subscription handler is called whenever the subscription state of an + * eventgroup changes. The callback is called with the client identifier + * and a boolean that indicates whether the client subscribed or + * unsubscribed. + * + * \param _service Service identifier of service instance whose + * subscription state is to be monitored. + * \param _instance Instance identifier of service instance whose + * subscription state is to be monitored. + * \param _eventgroup Eventgroup identifier of eventgroup whose + * subscription state is to be monitored. + * \param _handler Callback that shall be called. + * + */ + virtual void register_async_subscription_handler(service_t _service, instance_t _instance, eventgroup_t _eventgroup, async_subscription_handler_t _handler) = 0; +}; + +/** @} */ + +} // namespace vsomeip + +#endif // VSOMEIP_APPLICATION_HPP |