1 // Copyright (C) 2014-2017 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) 2 // This Source Code Form is subject to the terms of the Mozilla Public 3 // License, v. 2.0. If a copy of the MPL was not distributed with this 4 // file, You can obtain one at http://mozilla.org/MPL/2.0/. 5 6 #ifndef VSOMEIP_V3_RUNTIME_HPP 7 #define VSOMEIP_V3_RUNTIME_HPP 8 9 #include <memory> 10 #include <string> 11 #include <vector> 12 13 #include <vsomeip/export.hpp> 14 #include <vsomeip/primitive_types.hpp> 15 16 namespace vsomeip_v3 { 17 18 class application; 19 class message; 20 class payload; 21 22 /** 23 * 24 * \defgroup vsomeip 25 * 26 * The vsomeip module contains all elements a user applications needs to: 27 * 28 * - offer SOME/IP service instances 29 * - request SOME/IP service instances 30 * - offer SOME/IP eventgroups 31 * - subscribe to SOME/IP eventgroups 32 * - send and receive SOME/IP messages (request/response) 33 * - implement SOME/IP events and fields 34 * 35 * @{ 36 * 37 */ 38 39 /** 40 * 41 * \brief Singleton class containing all public resource management 42 * facilities of vsomeip. 43 * 44 * The methods of this class shall be used to create instances of all the 45 * classes needed to facilitate SOME/IP communication. In particular, it is 46 * the entry point to create instances of the @ref application class that 47 * contains the main public API of vsomeip. 48 * 49 */ 50 class VSOMEIP_IMPORT_EXPORT runtime { 51 public: 52 53 static std::string get_property(const std::string &_name); 54 static void set_property(const std::string &_name, const std::string &_value); 55 56 static std::shared_ptr<runtime> get(); 57 ~runtime()58 virtual ~runtime() { 59 } 60 61 /** 62 * 63 * \brief Creates a vsomeip application object. 64 * 65 * An application object manages service offers and requests as well as 66 * event subscriptions. It allows to register user application functions 67 * as callbacks that are called on specific events during runtime, e.g 68 * to react on incoming SOME/IP messages. 69 * An application object is identified by a unique name that is also used 70 * in (and therefore has to match) the configuration files of vsomeip. If 71 * the name is left empty, the application name is taken from the 72 * environment variable "VSOMEIP_APPLICATION_NAME" 73 * 74 * \param _name Name of the application on the system. 75 * 76 */ 77 virtual std::shared_ptr<application> create_application( 78 const std::string &_name = "") = 0; 79 80 /** 81 * 82 * \brief Constructs an empty message object. 83 * 84 * The message can then be used to call @application::send to send a 85 * SOME/IP message. The user application is responsible for setting 86 * the message type, the service instance and the message payload 87 * after this call and before calling @application::send. 88 * 89 * \param _reliable Determines whether this message shall be sent 90 * over a reliable connection (TCP) or not (UDP). 91 * 92 */ 93 virtual std::shared_ptr<message> create_message( 94 bool _reliable = false) const = 0; 95 /** 96 * 97 * \brief Constructs an empty request message. 98 * 99 * The message can then be used to call @ref application::send to send a 100 * SOME/IP message. The message type is set to REQUEST after the 101 * call and the request identifier is automatically set during the 102 * @ref application::send call. 103 * 104 * The user application is responsible for setting the service instance 105 * and the payload. 106 * 107 * \param _reliable Determines whether this message shall be sent 108 * over a reliable connection (TCP) or not (UDP). 109 * 110 */ 111 virtual std::shared_ptr<message> create_request( 112 bool _reliable = false) const = 0; 113 114 /* 115 * \brief Constructs an empty response message from a given request 116 * message. 117 * 118 * The message can then be used to call @ref application::send to send a 119 * SOME/IP message. The message type is set to RESPONSE after the 120 * call and the request identifier is automatically set from the 121 * request message. 122 * 123 * The user application is responsible for setting the service instance 124 * and the payload. 125 * 126 * \param _request The request message that shall be answered by 127 * the response message. 128 * 129 */ 130 virtual std::shared_ptr<message> create_response( 131 const std::shared_ptr<message> &_request) const = 0; 132 133 /** 134 * 135 * \brief Creates an empty notification message. 136 * 137 * The message can then be used to call @ref application::send to send a 138 * SOME/IP message. The message type is set to NOTIFICATION after the 139 * call. 140 * 141 * The user application is responsible for setting the service instance 142 * and the payload. 143 * 144 * \param _reliable Determines whether this message shall be sent 145 * over a reliable connection (TCP) or not (UDP). 146 * 147 * Note: Creating notification messages and sending them using 148 * @ref application::send is possible but not the standard way of sending 149 * notification with vsomeip. The standard way is calling 150 * @ref application::offer_event and setting the value using the 151 * @ref application::notify / @ref application::notify_one methods. 152 * 153 */ 154 virtual std::shared_ptr<message> create_notification( 155 bool _reliable = false) const = 0; 156 157 /** 158 * 159 * \brief Creates an empty payload object. 160 * 161 */ 162 virtual std::shared_ptr<payload> create_payload() const = 0; 163 164 /** 165 * 166 * \brief Creates a payload object filled with the given data. 167 * 168 * \param _data Bytes to be copied into the payload object. 169 * \param _size Number of bytes to be copied into the payload object. 170 * 171 */ 172 virtual std::shared_ptr<payload> create_payload( 173 const byte_t *_data, uint32_t _size) const = 0; 174 175 /** 176 * 177 * \brief Creates a payload object filled with the given data. 178 * 179 * \param _data Bytes to be copied into the payload object. 180 * 181 */ 182 virtual std::shared_ptr<payload> create_payload( 183 const std::vector<byte_t> &_data) const = 0; 184 185 /** 186 * 187 * \brief Retrieves the application object for the application with the 188 * given name. 189 * 190 * If no such application is found, an empty shared_ptr is returned 191 * (nullptr). 192 * 193 * \param _name Name of the application to be found. 194 * 195 */ 196 virtual std::shared_ptr<application> get_application( 197 const std::string &_name) const = 0; 198 199 /** 200 * 201 * \brief Removes the application object for the application with the 202 * given name. 203 * 204 * If no such application is found, this is a null operation. 205 * 206 * \param _name Name of the application to be removed. 207 * 208 */ 209 virtual void remove_application( const std::string &_name) = 0; 210 }; 211 212 /** @} */ 213 214 } // namespace vsomeip_v3 215 216 #endif // VSOMEIP_V3_RUNTIME_HPP_ 217