VLink  2.3.0
A high-performance communication middleware
mqtt_conf.h
浏览该文件的文档.
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 mqtt_conf.h
26  * @brief Transport configuration for the @c mqtt:// MQTT broker bridge.
27  *
28  * @details
29  * @c MqttConf binds the @c mqtt:// URL scheme to the Eclipse Paho MQTT C client.
30  * MQTT is a lightweight publish/subscribe protocol designed for constrained
31  * devices, intermittent links, and low-bandwidth wide-area networks; it always
32  * routes through a broker (no peer-to-peer mode). Use this transport to bridge
33  * VLink topics to a cloud / fleet MQTT broker, or to interoperate with existing
34  * MQTT-based telemetry pipelines.
35  *
36  * @par Supported Node Types
37  *
38  * | Publisher | Subscriber | Server | Client | Getter | Setter |
39  * | :-------: | :--------: | :----: | :----: | :----: | :----: |
40  * | yes | yes | yes | yes | yes | yes |
41  *
42  * @par URL Format
43  * @code
44  * mqtt://<address>[?event=<name>&domain=<N>&qos=<0|1|2>][#<broker_uri>]
45  * @endcode
46  *
47  * | Component | Description |
48  * | ---------- | -------------------------------------------------------------------------- |
49  * | @c address | MQTT topic path (URL host concatenated with path) |
50  * | @c event | Optional secondary event filter (@c ?event=) |
51  * | @c domain | Domain / namespace identifier (@c ?domain=); factory default applied |
52  * | @c qos | MQTT QoS level @c 0, @c 1 or @c 2 (@c ?qos=); factory default applied |
53  * | @c fragment| Optional broker URI override carried in the URL fragment |
54  *
55  * @par Broker Connection
56  *
57  * | Property | Source | Description |
58  * | ---------------- | ---------------------------- | ------------------------------------ |
59  * | Broker URI | @c VLINK_MQTT_BROKER env var | @c tcp:// / @c ssl:// / @c ws:// URI |
60  * | Domain ID | @c VLINK_MQTT_DOMAIN env var | Default @c ?domain= when absent |
61  * | QoS level | @c VLINK_MQTT_QOS env var | Default @c 0, @c 1 or @c 2 |
62  * | Keep-alive (s) | @c VLINK_MQTT_KEEPALIVE env | MQTT keep-alive interval |
63  * | Client ID prefix | @c VLINK_MQTT_CLIENT_ID env | Prefix used for generated client IDs |
64  *
65  * @par TLS Configuration
66  *
67  * | Property | Description |
68  * | --------------------- | ---------------------------------------------------------- |
69  * | @c ssl:// URI scheme | Selects TLS transport instead of plain TCP |
70  * | CA certificate file | Configured through @c set_property("ssl.ca", path) |
71  * | Client certificate | Configured through @c set_property("ssl.cert", path) |
72  * | Client private key | Configured through @c set_property("ssl.key", path) |
73  *
74  * @par Example
75  * @code
76  * // Defaults inherit broker URI and QoS from environment variables:
77  * auto pub = vlink::Publisher<MyMsg>::create_unique("mqtt://telemetry/state?qos=1");
78  *
79  * // Override broker URI via URL fragment:
80  * auto sub = vlink::Subscriber<MyMsg>::create_unique("mqtt://telemetry/state#tcp://10.0.0.5:1883");
81  * @endcode
82  *
83  * @note Compiled only when @c VLINK_SUPPORT_MQTT is defined.
84  * @note URL parsing uses @c MqttFactory::get_default_domain_id() and
85  * @c MqttFactory::get_default_qos() when @c domain or @c qos are omitted;
86  * direct construction defaults remain @c domain=0 and @c qos=1.
87  * @note @c is_valid() returns @c false when @c address is empty, @c domain is
88  * negative, or @c qos is outside @c [0, 2].
89  */
90 
91 #pragma once
92 
93 #ifdef VLINK_SUPPORT_MQTT
94 
95 #include <cstdint>
96 #include <map>
97 #include <shared_mutex>
98 #include <string>
99 
100 #include "../impl/conf.h"
101 
102 namespace vlink {
103 
104 /**
105  * @struct MqttConf
106  * @brief Concrete @c Conf describing an MQTT endpoint addressed by an @c mqtt:// URL.
107  *
108  * @details
109  * Stores the MQTT topic path, optional secondary event filter, domain identifier,
110  * MQTT QoS level, and an optional broker URI override carried in the URL fragment.
111  */
112 struct VLINK_EXPORT MqttConf final : public Conf {
113  std::string address; ///< MQTT topic path (URL host concatenated with path).
114  std::string event; ///< Optional secondary event filter string.
115  int32_t domain{0}; ///< Domain / namespace identifier (non-negative).
116  int32_t qos{1}; ///< MQTT QoS level; @c 0, @c 1 or @c 2.
117  std::string fragment; ///< Optional broker URI override carried in the URL fragment.
118 
119  /**
120  * @brief Builds an @c MqttConf from its five logical fields.
121  *
122  * @param _address MQTT topic path.
123  * @param _event Optional event filter; empty by default.
124  * @param _domain Domain identifier; defaults to @c 0.
125  * @param _qos MQTT QoS level; defaults to @c 1.
126  * @param _fragment Optional broker URI override; empty by default.
127  */
128  explicit MqttConf(const std::string& _address, const std::string& _event = "", int32_t _domain = 0, int32_t _qos = 1,
129  const std::string& _fragment = "");
130 
131  /**
132  * @brief Component-wise equality on all configuration fields.
133  *
134  * @param conf Configuration to compare with.
135  * @return @c true when every field of @c *this matches @p conf.
136  */
137  [[nodiscard]] bool operator==(const MqttConf& conf) const noexcept;
138 
139  /**
140  * @brief Logical negation of @c operator==.
141  *
142  * @param conf Configuration to compare with.
143  * @return @c true when any field differs from @p conf.
144  */
145  [[nodiscard]] bool operator!=(const MqttConf& conf) const noexcept;
146 
147  /**
148  * @brief Reports this object's transport tag.
149  *
150  * @return @c TransportType::kMqtt.
151  */
152  [[nodiscard]] TransportType get_transport_type() const override;
153 
154  static constexpr const char* kRespSuffix{"___resp"}; ///< Suffix appended to RPC reply topic names.
155 
156 #ifndef VLINK_ENABLE_C_INTERFACE
158 #endif
160  VLINK_CONF_IMPL(MqttConf)
161 };
162 
163 ////////////////////////////////////////////////////////////////
164 /// Details
165 ////////////////////////////////////////////////////////////////
166 
167 inline MqttConf::MqttConf(const std::string& _address, const std::string& _event, int32_t _domain, int32_t _qos,
168  const std::string& _fragment)
169  : address(_address), event(_event), domain(_domain), qos(_qos), fragment(_fragment) {}
170 
171 inline bool MqttConf::operator==(const MqttConf& conf) const noexcept {
172  return address == conf.address && event == conf.event && domain == conf.domain && qos == conf.qos &&
173  fragment == conf.fragment;
174 }
175 
176 inline bool MqttConf::operator!=(const MqttConf& conf) const noexcept { return !(*this == conf); }
177 
178 inline TransportType MqttConf::get_transport_type() const { return TransportType::kMqtt; }
179 
180 } // namespace vlink
181 
182 #endif
#define VLINK_CONF_IMPL(classname)
Convenience macro that emits the standard concrete conf boilerplate.
Definition: conf.h:250
#define VLINK_DECLARE_GLOBAL_PROPERTY()
Declares per-transport static configuration storage and access helpers.
Definition: conf.h:308
#define VLINK_ALLOW_IMPL_TYPE(type)
Records the bitmask of ImplType values supported by a conf.
Definition: conf.h:291
#define VLINK_EXPORT
Definition: macros.h:81