WPILibC++ 2025.2.1
Loading...
Searching...
No Matches
Topic.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <stdint.h>
8
9#include <string>
10#include <string_view>
11#include <utility>
12#include <vector>
13
14#include <wpi/json_fwd.h>
15
17#include "ntcore_c.h"
18#include "ntcore_cpp.h"
19
20namespace nt {
21
22class GenericEntry;
23class GenericPublisher;
24class GenericSubscriber;
25class NetworkTableInstance;
26
27/** NetworkTables Topic. */
28class Topic {
29 public:
30 Topic() = default;
31 explicit Topic(NT_Topic handle) : m_handle{handle} {}
32
33 /**
34 * Determines if the native handle is valid.
35 *
36 * @return True if the native handle is valid, false otherwise.
37 */
38 explicit operator bool() const { return m_handle != 0; }
39
40 /**
41 * Gets the native handle for the topic.
42 *
43 * @return Native handle
44 */
45 NT_Topic GetHandle() const { return m_handle; }
46
47 /**
48 * Gets the instance for the topic.
49 *
50 * @return Instance
51 */
53
54 /**
55 * Gets the name of the topic.
56 *
57 * @return the topic's name
58 */
59 std::string GetName() const { return ::nt::GetTopicName(m_handle); }
60
61 /**
62 * Gets the type of the topic.
63 *
64 * @return the topic's type
65 */
67 return static_cast<NetworkTableType>(::nt::GetTopicType(m_handle));
68 }
69
70 /**
71 * Gets the type string of the topic. This may have more information
72 * than the numeric type (especially for raw values).
73 *
74 * @return the topic's type
75 */
76 std::string GetTypeString() const {
77 return ::nt::GetTopicTypeString(m_handle);
78 }
79
80 /**
81 * Make value persistent through server restarts.
82 *
83 * @param persistent True for persistent, false for not persistent.
84 */
85 void SetPersistent(bool persistent) {
87 }
88
89 /**
90 * Returns whether the value is persistent through server restarts.
91 *
92 * @return True if the value is persistent.
93 */
94 bool IsPersistent() const { return ::nt::GetTopicPersistent(m_handle); }
95
96 /**
97 * Make the server retain the topic even when there are no publishers.
98 *
99 * @param retained True for retained, false for not retained.
100 */
101 void SetRetained(bool retained) {
103 }
104
105 /**
106 * Returns whether the topic is retained by server when there are no
107 * publishers.
108 *
109 * @return True if the topic is retained.
110 */
111 bool IsRetained() const { return ::nt::GetTopicRetained(m_handle); }
112
113 /**
114 * Allow storage of the topic's last value, allowing the value to be read (and
115 * not just accessed through event queues and listeners).
116 *
117 * @param cached True for cached, false for not cached.
118 */
119 void SetCached(bool cached) { ::nt::SetTopicCached(m_handle, cached); }
120
121 /**
122 * Returns whether the topic's last value is stored.
123 *
124 * @return True if the topic is cached.
125 */
126 bool IsCached() const { return ::nt::GetTopicCached(m_handle); }
127
128 /**
129 * Determines if the topic is currently being published.
130 *
131 * @return True if the topic exists, false otherwise.
132 */
133 bool Exists() const { return nt::GetTopicExists(m_handle); }
134
135 /**
136 * Gets the current value of a property (as a JSON object).
137 *
138 * @param name property name
139 * @return JSON object; null object if the property does not exist.
140 */
141 wpi::json GetProperty(std::string_view name) const;
142
143 /**
144 * Sets a property value.
145 *
146 * @param name property name
147 * @param value property value
148 */
149 void SetProperty(std::string_view name, const wpi::json& value);
150
151 /**
152 * Deletes a property. Has no effect if the property does not exist.
153 *
154 * @param name property name
155 */
156 void DeleteProperty(std::string_view name) {
158 }
159
160 /**
161 * Gets all topic properties as a JSON object. Each key in the object
162 * is the property name, and the corresponding value is the property value.
163 *
164 * @return JSON object
165 */
166 wpi::json GetProperties() const;
167
168 /**
169 * Updates multiple topic properties. Each key in the passed-in object is
170 * the name of the property to add/update, and the corresponding value is the
171 * property value to set for that property. Null values result in deletion
172 * of the corresponding property.
173 *
174 * @param properties JSON object with keys to add/update/delete
175 * @return False if properties is not an object
176 */
177 bool SetProperties(const wpi::json& properties) {
178 return ::nt::SetTopicProperties(m_handle, properties);
179 }
180
181 /**
182 * Gets combined information about the topic.
183 *
184 * @return Topic information
185 */
186 TopicInfo GetInfo() const { return ::nt::GetTopicInfo(m_handle); }
187
188 /**
189 * Create a new subscriber to the topic.
190 *
191 * <p>The subscriber is only active as long as the returned object
192 * is not destroyed.
193 *
194 * @param options subscribe options
195 * @return subscriber
196 */
197 [[nodiscard]]
199 const PubSubOptions& options = kDefaultPubSubOptions);
200
201 /**
202 * Create a new subscriber to the topic.
203 *
204 * <p>The subscriber is only active as long as the returned object
205 * is not destroyed.
206 *
207 * @note Subscribers that do not match the published data type do not return
208 * any values. To determine if the data type matches, use the appropriate
209 * Topic functions.
210 *
211 * @param typeString type string
212 * @param options subscribe options
213 * @return subscriber
214 */
215 [[nodiscard]]
217 std::string_view typeString,
218 const PubSubOptions& options = kDefaultPubSubOptions);
219
220 /**
221 * Create a new publisher to the topic.
222 *
223 * The publisher is only active as long as the returned object
224 * is not destroyed.
225 *
226 * @note It is not possible to publish two different data types to the same
227 * topic. Conflicts between publishers are typically resolved by the
228 * server on a first-come, first-served basis. Any published values that
229 * do not match the topic's data type are dropped (ignored). To determine
230 * if the data type matches, use the appropriate Topic functions.
231 *
232 * @param typeString type string
233 * @param options publish options
234 * @return publisher
235 */
236 [[nodiscard]]
238 std::string_view typeString,
239 const PubSubOptions& options = kDefaultPubSubOptions);
240
241 /**
242 * Create a new publisher to the topic, with type string and initial
243 * properties.
244 *
245 * The publisher is only active as long as the returned object
246 * is not destroyed.
247 *
248 * @note It is not possible to publish two different data types to the same
249 * topic. Conflicts between publishers are typically resolved by the
250 * server on a first-come, first-served basis. Any published values that
251 * do not match the topic's data type are dropped (ignored). To determine
252 * if the data type matches, use the appropriate Topic functions.
253 *
254 * @param typeString type string
255 * @param properties JSON properties
256 * @param options publish options
257 * @return publisher
258 */
259 [[nodiscard]]
261 std::string_view typeString, const wpi::json& properties,
262 const PubSubOptions& options = kDefaultPubSubOptions);
263
264 /**
265 * Create a new generic entry for the topic.
266 *
267 * Entries act as a combination of a subscriber and a weak publisher. The
268 * subscriber is active as long as the entry is not destroyed. The publisher
269 * is created when the entry is first written to, and remains active until
270 * either Unpublish() is called or the entry is destroyed.
271 *
272 * @note It is not possible to use two different data types with the same
273 * topic. Conflicts between publishers are typically resolved by the
274 * server on a first-come, first-served basis. Any published values that
275 * do not match the topic's data type are dropped (ignored), and the entry
276 * will show no new values if the data type does not match. To determine
277 * if the data type matches, use the appropriate Topic functions.
278 *
279 * @param options publish and/or subscribe options
280 * @return entry
281 */
282 [[nodiscard]]
284 const PubSubOptions& options = kDefaultPubSubOptions);
285
286 /**
287 * Create a new generic entry for the topic.
288 *
289 * Entries act as a combination of a subscriber and a weak publisher. The
290 * subscriber is active as long as the entry is not destroyed. The publisher
291 * is created when the entry is first written to, and remains active until
292 * either Unpublish() is called or the entry is destroyed.
293 *
294 * @note It is not possible to use two different data types with the same
295 * topic. Conflicts between publishers are typically resolved by the
296 * server on a first-come, first-served basis. Any published values that
297 * do not match the topic's data type are dropped (ignored), and the entry
298 * will show no new values if the data type does not match. To determine
299 * if the data type matches, use the appropriate Topic functions.
300 *
301 * @param typeString type string
302 * @param options publish and/or subscribe options
303 * @return entry
304 */
305 [[nodiscard]]
307 std::string_view typeString,
308 const PubSubOptions& options = kDefaultPubSubOptions);
309
310 /**
311 * Equality operator. Returns true if both instances refer to the same
312 * native handle.
313 */
314 bool operator==(const Topic&) const = default;
315
316 protected:
318};
319
320/** NetworkTables subscriber. */
322 public:
324
325 Subscriber(const Subscriber&) = delete;
326 Subscriber& operator=(const Subscriber&) = delete;
327
329 rhs.m_subHandle = 0;
330 }
331
333 if (m_subHandle != 0) {
335 }
337 rhs.m_subHandle = 0;
338 return *this;
339 }
340
341 /**
342 * Determines if the native handle is valid.
343 *
344 * @return True if the native handle is valid, false otherwise.
345 */
346 explicit operator bool() const { return m_subHandle != 0; }
347
348 /**
349 * Gets the native handle for the subscriber.
350 *
351 * @return Native handle
352 */
354
355 /**
356 * Determines if the topic is currently being published.
357 *
358 * @return True if the topic exists, false otherwise.
359 */
360 bool Exists() const { return nt::GetTopicExists(m_subHandle); }
361
362 /**
363 * Gets the last time the value was changed.
364 * Note: this is not atomic with Get(); use GetAtomic() to get
365 * both the value and last change as an atomic operation.
366 *
367 * @return Topic last change time
368 */
369 int64_t GetLastChange() const {
370 return ::nt::GetEntryLastChange(m_subHandle);
371 }
372
373 /**
374 * Gets the subscribed-to topic.
375 *
376 * @return Topic
377 */
381
382 protected:
383 Subscriber() = default;
384 explicit Subscriber(NT_Subscriber handle) : m_subHandle{handle} {}
385
387
388 private:
389 void anchor();
390};
391
392/** NetworkTables publisher. */
394 public:
396
397 Publisher(const Publisher&) = delete;
398 Publisher& operator=(const Publisher&) = delete;
399
401 rhs.m_pubHandle = 0;
402 }
403
405 if (m_pubHandle != 0) {
407 }
409 rhs.m_pubHandle = 0;
410 return *this;
411 }
412
413 /**
414 * Determines if the native handle is valid.
415 *
416 * @return True if the native handle is valid, false otherwise.
417 */
418 explicit operator bool() const { return m_pubHandle != 0; }
419
420 /**
421 * Gets the native handle for the publisher.
422 *
423 * @return Native handle
424 */
426
427 /**
428 * Gets the published-to topic.
429 *
430 * @return Topic
431 */
435
436 protected:
437 Publisher() = default;
438 explicit Publisher(NT_Publisher handle) : m_pubHandle{handle} {}
439
440 /// NetworkTables handle.
442
443 private:
444 void anchor();
445};
446
447} // namespace nt
NetworkTables generic entry.
Definition GenericEntry.h:511
NetworkTables generic publisher.
Definition GenericEntry.h:219
NetworkTables generic subscriber.
Definition GenericEntry.h:24
NetworkTables Instance.
Definition NetworkTableInstance.h:68
NetworkTables publisher.
Definition Topic.h:393
Publisher(const Publisher &)=delete
Publisher(NT_Publisher handle)
Definition Topic.h:438
Topic GetTopic() const
Gets the published-to topic.
Definition Topic.h:432
Publisher(Publisher &&rhs)
Definition Topic.h:400
Publisher & operator=(const Publisher &)=delete
Publisher()=default
NT_Publisher m_pubHandle
NetworkTables handle.
Definition Topic.h:441
NT_Publisher GetHandle() const
Gets the native handle for the publisher.
Definition Topic.h:425
virtual ~Publisher()
Definition Topic.h:395
Publisher & operator=(Publisher &&rhs)
Definition Topic.h:404
NetworkTables subscriber.
Definition Topic.h:321
bool Exists() const
Determines if the topic is currently being published.
Definition Topic.h:360
int64_t GetLastChange() const
Gets the last time the value was changed.
Definition Topic.h:369
NT_Subscriber GetHandle() const
Gets the native handle for the subscriber.
Definition Topic.h:353
virtual ~Subscriber()
Definition Topic.h:323
Subscriber & operator=(Subscriber &&rhs)
Definition Topic.h:332
Subscriber & operator=(const Subscriber &)=delete
NT_Subscriber m_subHandle
Definition Topic.h:386
Subscriber(NT_Subscriber handle)
Definition Topic.h:384
Subscriber(Subscriber &&rhs)
Definition Topic.h:328
Topic GetTopic() const
Gets the subscribed-to topic.
Definition Topic.h:378
Subscriber()=default
Subscriber(const Subscriber &)=delete
NetworkTables Topic.
Definition Topic.h:28
GenericPublisher GenericPublishEx(std::string_view typeString, const wpi::json &properties, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new publisher to the topic, with type string and initial properties.
bool IsPersistent() const
Returns whether the value is persistent through server restarts.
Definition Topic.h:94
bool Exists() const
Determines if the topic is currently being published.
Definition Topic.h:133
Topic(NT_Topic handle)
Definition Topic.h:31
bool SetProperties(const wpi::json &properties)
Updates multiple topic properties.
Definition Topic.h:177
void DeleteProperty(std::string_view name)
Deletes a property.
Definition Topic.h:156
Topic()=default
void SetRetained(bool retained)
Make the server retain the topic even when there are no publishers.
Definition Topic.h:101
std::string GetTypeString() const
Gets the type string of the topic.
Definition Topic.h:76
GenericEntry GetGenericEntry(std::string_view typeString, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new generic entry for the topic.
GenericEntry GetGenericEntry(const PubSubOptions &options=kDefaultPubSubOptions)
Create a new generic entry for the topic.
NT_Topic GetHandle() const
Gets the native handle for the topic.
Definition Topic.h:45
NetworkTableType GetType() const
Gets the type of the topic.
Definition Topic.h:66
std::string GetName() const
Gets the name of the topic.
Definition Topic.h:59
bool IsRetained() const
Returns whether the topic is retained by server when there are no publishers.
Definition Topic.h:111
NT_Topic m_handle
Definition Topic.h:317
bool operator==(const Topic &) const =default
Equality operator.
void SetCached(bool cached)
Allow storage of the topic's last value, allowing the value to be read (and not just accessed through...
Definition Topic.h:119
bool IsCached() const
Returns whether the topic's last value is stored.
Definition Topic.h:126
void SetPersistent(bool persistent)
Make value persistent through server restarts.
Definition Topic.h:85
wpi::json GetProperties() const
Gets all topic properties as a JSON object.
GenericPublisher GenericPublish(std::string_view typeString, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new publisher to the topic.
wpi::json GetProperty(std::string_view name) const
Gets the current value of a property (as a JSON object).
NetworkTableInstance GetInstance() const
Gets the instance for the topic.
TopicInfo GetInfo() const
Gets combined information about the topic.
Definition Topic.h:186
void SetProperty(std::string_view name, const wpi::json &value)
Sets a property value.
GenericSubscriber GenericSubscribe(std::string_view typeString, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new subscriber to the topic.
GenericSubscriber GenericSubscribe(const PubSubOptions &options=kDefaultPubSubOptions)
Create a new subscriber to the topic.
NT_Handle NT_Topic
Definition ntcore_c.h:42
NT_Handle NT_Subscriber
Definition ntcore_c.h:43
NT_Handle NT_Publisher
Definition ntcore_c.h:44
NetworkTableType
NetworkTable entry type.
Definition NetworkTableType.h:15
constexpr PubSubOptions kDefaultPubSubOptions
Default publish/subscribe options.
Definition ntcore_cpp.h:390
NT_Topic GetTopicFromHandle(NT_Handle pubsubentry)
Gets the topic handle from an entry/subscriber/publisher handle.
void Release(NT_Handle pubsubentry)
Stops entry/subscriber/publisher.
bool GetTopicExists(NT_Handle handle)
Determine if topic exists (e.g.
NT_Type GetTopicType(NT_Topic topic)
Gets the type for the specified topic, or unassigned if non existent.
void SetTopicCached(NT_Topic topic, bool value)
Sets the cached property of a topic.
void SetTopicRetained(NT_Topic topic, bool value)
Sets the retained property of a topic.
void SetTopicPersistent(NT_Topic topic, bool value)
Sets the persistent property of a topic.
void DeleteTopicProperty(NT_Topic topic, std::string_view name)
Deletes a property.
NetworkTables (ntcore) namespace.
Definition ntcore_cpp.h:36
NetworkTables publish/subscribe options.
Definition ntcore_cpp.h:305
NetworkTables Topic Information.
Definition ntcore_cpp.h:90