VLink  2.0.0
A high-performance communication middleware
someip_conf.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file someip_conf.h
26  * @brief Transport configuration for the @c someip:// AUTOSAR SOME/IP transport.
27  *
28  * @details
29  * @c SomeipConf binds the @c someip:// URL scheme to vsomeip, the reference
30  * open-source implementation of the AUTOSAR SOME/IP (Scalable service-Oriented
31  * MiddlewarE over IP) protocol. SOME/IP is the standard service-oriented
32  * communication protocol used in modern automotive Ethernet backbones; it carries
33  * RPC method calls, event broadcasts and notifiable field updates between ECUs.
34  * Unlike string-named transports, SOME/IP identifies endpoints purely through
35  * 16-bit numeric identifiers.
36  *
37  * @par Supported Node Types
38  *
39  * | Publisher | Subscriber | Server | Client | Getter | Setter |
40  * | :-------: | :--------: | :----: | :----: | :----: | :----: |
41  * | yes | yes | yes | yes | yes | yes |
42  *
43  * @par SOME/IP Identifier Model
44  *
45  * | Field | Applies to | Description |
46  * | ------------- | ------------------ | ---------------------------------------------- |
47  * | @c service | all node types | 16-bit SOME/IP Service ID |
48  * | @c instance | all node types | 16-bit Service Instance ID |
49  * | @c method | Server / Client | 16-bit Method ID for RPC interfaces |
50  * | @c groups | Pub/Sub + Field | Set of 16-bit Event Group IDs |
51  * | @c event | Pub/Sub + Field | 16-bit Event ID within the selected groups |
52  * | @c field | Setter / Getter | @c true marks the endpoint as a SOME/IP field |
53  *
54  * @par URL Format
55  * @code
56  * // RPC (Server / Client):
57  * someip://<service>/<instance>?method=<method_id>
58  *
59  * // Event (Publisher / Subscriber):
60  * someip://<service>/<instance>?groups=<g1|g2|...>&event=<event_id>
61  *
62  * // Field (Setter / Getter):
63  * someip://<service>/<instance>?groups=<g1|g2|...>&event=<event_id>&field=1
64  * @endcode
65  *
66  * Numeric values are parsed by @c Helpers::to_int(), so decimal, @c 0x-prefixed
67  * hexadecimal, and leading-zero octal forms are all accepted. @c service and
68  * @c instance must be non-zero.
69  *
70  * @par Example
71  * @code
72  * // RPC server: service 0x1234, instance 0x5678, method 0x0001
73  * auto server = vlink::Server<MyReq, MyResp>::create_unique("someip://4660/22136?method=1");
74  *
75  * // Event publisher: service 0x1234, instance 0x5678, group 0x0001, event 0x0010
76  * auto pub = vlink::Publisher<MyMsg>::create_unique("someip://4660/22136?groups=1&event=16");
77  *
78  * // Direct construction:
79  * vlink::SomeipConf conf(0x1234, 0x5678, {0x0001}, 0x0010);
80  * auto pub2 = vlink::Publisher<MyMsg>::create_unique(conf);
81  * @endcode
82  *
83  * @par vsomeip Configuration
84  * A vsomeip JSON configuration file can be loaded process-wide before any
85  * endpoint is created:
86  * @code
87  * vlink::SomeipConf::load_global_config_file("/etc/vsomeip/vsomeip.json");
88  * @endcode
89  *
90  * @note Compiled only when @c VLINK_SUPPORT_SOMEIP is defined.
91  * @note @c service and @c instance must both be non-zero; otherwise @c is_valid()
92  * returns @c false.
93  * @note For @c kPublisher / @c kSubscriber / @c kSetter / @c kGetter, both
94  * @c groups and @c event must be set.
95  * @note For @c kSetter / @c kGetter, @c field must be @c true.
96  */
97 
98 #pragma once
99 
100 #ifdef VLINK_SUPPORT_SOMEIP
101 
102 #include <cstdint>
103 #include <set>
104 #include <string>
105 
106 #include "../impl/conf.h"
107 
108 namespace vlink {
109 
110 /**
111  * @struct SomeipConf
112  * @brief Concrete @c Conf describing a SOME/IP endpoint addressed by a @c someip:// URL.
113  *
114  * @details
115  * Two constructor overloads cover the two SOME/IP communication patterns: one for
116  * method-based RPC and one for event-group-based publish/subscribe and field
117  * synchronisation. The @c field flag distinguishes events from fields when the
118  * group-based constructor is used.
119  */
120 struct VLINK_EXPORT SomeipConf final : public Conf {
121  using Groups = std::set<uint16_t>; ///< Type alias for the set of SOME/IP Event Group IDs.
122 
123  uint16_t service{0}; ///< SOME/IP Service ID; must be non-zero for a valid configuration.
124  uint16_t instance{0}; ///< SOME/IP Service Instance ID; must be non-zero.
125  uint16_t method{0}; ///< SOME/IP Method ID; used by @c kServer / @c kClient endpoints only.
126  Groups groups; ///< Set of SOME/IP Event Group IDs; required for event and field endpoints.
127  uint16_t event{0}; ///< SOME/IP Event ID within the selected groups; required for event / field endpoints.
128  bool field{false}; ///< @c true when this endpoint is a SOME/IP field (@c kSetter / @c kGetter).
129 
130  /**
131  * @brief Builds a @c SomeipConf for an RPC endpoint (Server or Client).
132  *
133  * @param _service SOME/IP Service ID.
134  * @param _instance SOME/IP Service Instance ID.
135  * @param _method SOME/IP Method ID identifying the RPC interface.
136  */
137  explicit SomeipConf(uint16_t _service, uint16_t _instance, uint16_t _method);
138 
139  /**
140  * @brief Builds a @c SomeipConf for an event-group endpoint (Pub/Sub or Setter/Getter).
141  *
142  * @param _service SOME/IP Service ID.
143  * @param _instance SOME/IP Service Instance ID.
144  * @param _groups Set of SOME/IP Event Group IDs to subscribe to.
145  * @param _event SOME/IP Event ID within the chosen groups.
146  * @param _field @c true for field-style (Setter/Getter), @c false for event-style (Pub/Sub).
147  */
148  explicit SomeipConf(uint16_t _service, uint16_t _instance, const Groups& _groups, uint16_t _event,
149  bool _field = false);
150 
151  /**
152  * @brief Component-wise equality on all configuration fields.
153  *
154  * @param conf Configuration to compare with.
155  * @return @c true when @c service, @c instance, @c method, @c groups, @c event and @c field all match.
156  */
157  [[nodiscard]] bool operator==(const SomeipConf& conf) const noexcept;
158 
159  /**
160  * @brief Logical negation of @c operator==.
161  *
162  * @param conf Configuration to compare with.
163  * @return @c true when any field differs from @p conf.
164  */
165  [[nodiscard]] bool operator!=(const SomeipConf& conf) const noexcept;
166 
167  /**
168  * @brief Reports this object's transport tag.
169  *
170  * @return @c TransportType::kSomeip.
171  */
172  [[nodiscard]] TransportType get_transport_type() const override;
173 
174  /**
175  * @brief Sets a vsomeip JSON configuration file as the process-wide default.
176  *
177  * @details
178  * Delegates to @c SomeipFactory::load_global_config_file(), which exports the
179  * @c VSOMEIP_CONFIGURATION environment variable so vsomeip can read the file
180  * during application initialisation. Must be called before any @c someip://
181  * endpoint is created.
182  *
183  * @param filepath Path to the vsomeip JSON configuration file.
184  * @return @c true when the environment variable was successfully set, @c false otherwise.
185  */
186  static bool load_global_config_file(const std::string& filepath);
187 
188 #ifndef VLINK_ENABLE_C_INTERFACE
189  VLINK_DECLARE_GLOBAL_PROPERTY()
190 #endif
191  VLINK_ALLOW_IMPL_TYPE(kServer | kClient | kPublisher | kSubscriber | kSetter | kGetter)
192  VLINK_CONF_IMPL(SomeipConf)
193 };
194 
195 ////////////////////////////////////////////////////////////////
196 /// Details
197 ////////////////////////////////////////////////////////////////
198 
199 inline SomeipConf::SomeipConf(uint16_t _service, uint16_t _instance, uint16_t _method)
200  : service(_service), instance(_instance), method(_method) {}
201 
202 inline SomeipConf::SomeipConf(uint16_t _service, uint16_t _instance, const Groups& _groups, uint16_t _event,
203  bool _field)
204  : service(_service), instance(_instance), groups(_groups), event(_event), field(_field) {}
205 
206 inline bool SomeipConf::operator==(const SomeipConf& conf) const noexcept {
207  return service == conf.service && instance == conf.instance && method == conf.method && groups == conf.groups &&
208  event == conf.event && field == conf.field;
209 }
210 
211 inline bool SomeipConf::operator!=(const SomeipConf& conf) const noexcept { return !(*this == conf); }
212 
213 inline TransportType SomeipConf::get_transport_type() const { return TransportType::kSomeip; }
214 
215 } // namespace vlink
216 
217 #endif
VLINK_CONF_IMPL
#define VLINK_CONF_IMPL(classname)
Convenience macro that emits the standard concrete conf boilerplate.
Definition: conf.h:251
VLINK_DECLARE_GLOBAL_PROPERTY
#define VLINK_DECLARE_GLOBAL_PROPERTY()
Declares per-transport static configuration storage and access helpers.
Definition: conf.h:309
VLINK_ALLOW_IMPL_TYPE
#define VLINK_ALLOW_IMPL_TYPE(type)
Records the bitmask of ImplType values supported by a conf.
Definition: conf.h:292
VLINK_EXPORT
#define VLINK_EXPORT
Definition: macros.h:81