mirror of
https://github.com/wpilibsuite/allwpilib
synced 2026-07-01 02:41:48 +00:00
549 lines
17 KiB
C++
549 lines
17 KiB
C++
/*----------------------------------------------------------------------------*/
|
|
/* Copyright (c) FIRST 2017-2018. All Rights Reserved. */
|
|
/* Open Source Software - may be modified and shared by FRC teams. The code */
|
|
/* must be accompanied by the FIRST BSD license file in the root directory of */
|
|
/* the project. */
|
|
/*----------------------------------------------------------------------------*/
|
|
|
|
#ifndef NTCORE_NETWORKTABLES_NETWORKTABLEINSTANCE_H_
|
|
#define NTCORE_NETWORKTABLES_NETWORKTABLEINSTANCE_H_
|
|
|
|
#include <functional>
|
|
#include <memory>
|
|
#include <string>
|
|
#include <utility>
|
|
#include <vector>
|
|
|
|
#include <llvm/ArrayRef.h>
|
|
#include <llvm/StringRef.h>
|
|
#include <llvm/Twine.h>
|
|
|
|
#include "networktables/NetworkTable.h"
|
|
#include "networktables/NetworkTableEntry.h"
|
|
#include "ntcore_c.h"
|
|
#include "ntcore_cpp.h"
|
|
|
|
#ifndef NT_NOEXCEPT
|
|
#ifdef _MSC_VER
|
|
#if _MSC_VER >= 1900
|
|
#define NT_NOEXCEPT noexcept
|
|
#else
|
|
#define NT_NOEXCEPT throw()
|
|
#endif
|
|
#else
|
|
#define NT_NOEXCEPT noexcept
|
|
#endif
|
|
#endif
|
|
|
|
namespace nt {
|
|
|
|
using llvm::ArrayRef;
|
|
using llvm::StringRef;
|
|
using llvm::Twine;
|
|
|
|
/** NetworkTables Instance.
|
|
*
|
|
* Instances are completely independent from each other. Table operations on
|
|
* one instance will not be visible to other instances unless the instances are
|
|
* connected via the network. The main limitation on instances is that you
|
|
* cannot have two servers on the same network port. The main utility of
|
|
* instances is for unit testing, but they can also enable one program to
|
|
* connect to two different NetworkTables networks.
|
|
*
|
|
* The global "default" instance (as returned by GetDefault()) is
|
|
* always available, and is intended for the common case when there is only
|
|
* a single NetworkTables instance being used in the program. The
|
|
* default instance cannot be destroyed.
|
|
*
|
|
* Additional instances can be created with the Create() function.
|
|
* Instances are not reference counted or RAII. Instead, they must be
|
|
* explicitly destroyed (with Destroy()).
|
|
*/
|
|
class NetworkTableInstance final {
|
|
public:
|
|
/**
|
|
* Client/server mode flag values (as returned by GetNetworkMode()).
|
|
* This is a bitmask.
|
|
*/
|
|
enum NetworkMode {
|
|
kNetModeNone = NT_NET_MODE_NONE,
|
|
kNetModeServer = NT_NET_MODE_SERVER,
|
|
kNetModeClient = NT_NET_MODE_CLIENT,
|
|
kNetModeStarting = NT_NET_MODE_STARTING,
|
|
kNetModeFailure = NT_NET_MODE_FAILURE
|
|
};
|
|
|
|
/**
|
|
* Logging levels (as used by SetLogger()).
|
|
*/
|
|
enum LogLevel {
|
|
kLogCritical = NT_LOG_CRITICAL,
|
|
kLogError = NT_LOG_ERROR,
|
|
kLogWarning = NT_LOG_WARNING,
|
|
kLogInfo = NT_LOG_INFO,
|
|
kLogDebug = NT_LOG_DEBUG,
|
|
kLogDebug1 = NT_LOG_DEBUG1,
|
|
kLogDebug2 = NT_LOG_DEBUG2,
|
|
kLogDebug3 = NT_LOG_DEBUG3,
|
|
kLogDebug4 = NT_LOG_DEBUG4
|
|
};
|
|
|
|
/**
|
|
* The default port that network tables operates on.
|
|
*/
|
|
enum { kDefaultPort = NT_DEFAULT_PORT };
|
|
|
|
/**
|
|
* Construct invalid instance.
|
|
*/
|
|
NetworkTableInstance() NT_NOEXCEPT;
|
|
|
|
/**
|
|
* Construct from native handle.
|
|
* @param handle Native handle
|
|
*/
|
|
explicit NetworkTableInstance(NT_Inst inst) NT_NOEXCEPT;
|
|
|
|
/**
|
|
* Determines if the native handle is valid.
|
|
* @return True if the native handle is valid, false otherwise.
|
|
*/
|
|
explicit operator bool() const { return m_handle != 0; }
|
|
|
|
/**
|
|
* Get global default instance.
|
|
* @return Global default instance
|
|
*/
|
|
static NetworkTableInstance GetDefault();
|
|
|
|
/**
|
|
* Create an instance.
|
|
* @return Newly created instance
|
|
*/
|
|
static NetworkTableInstance Create();
|
|
|
|
/**
|
|
* Destroys an instance (note: this has global effect).
|
|
* @param inst Instance
|
|
*/
|
|
static void Destroy(NetworkTableInstance inst);
|
|
|
|
/**
|
|
* Gets the native handle for the entry.
|
|
* @return Native handle
|
|
*/
|
|
NT_Inst GetHandle() const;
|
|
|
|
/**
|
|
* Gets the entry for a key.
|
|
* @param name Key
|
|
* @return Network table entry.
|
|
*/
|
|
NetworkTableEntry GetEntry(const Twine& name);
|
|
|
|
/**
|
|
* Get entries starting with the given prefix.
|
|
* The results are optionally filtered by string prefix and entry type to
|
|
* only return a subset of all entries.
|
|
*
|
|
* @param prefix entry name required prefix; only entries whose name
|
|
* starts with this string are returned
|
|
* @param types bitmask of types; 0 is treated as a "don't care"
|
|
* @return Array of entries.
|
|
*/
|
|
std::vector<NetworkTableEntry> GetEntries(const Twine& prefix,
|
|
unsigned int types);
|
|
|
|
/**
|
|
* Get information about entries starting with the given prefix.
|
|
* The results are optionally filtered by string prefix and entry type to
|
|
* only return a subset of all entries.
|
|
*
|
|
* @param prefix entry name required prefix; only entries whose name
|
|
* starts with this string are returned
|
|
* @param types bitmask of types; 0 is treated as a "don't care"
|
|
* @return Array of entry information.
|
|
*/
|
|
std::vector<EntryInfo> GetEntryInfo(const Twine& prefix,
|
|
unsigned int types) const;
|
|
|
|
/**
|
|
* Gets the table with the specified key.
|
|
*
|
|
* @param key the key name
|
|
* @return The network table
|
|
*/
|
|
std::shared_ptr<NetworkTable> GetTable(const Twine& key) const;
|
|
|
|
/**
|
|
* Deletes ALL keys in ALL subtables (except persistent values).
|
|
* Use with caution!
|
|
*/
|
|
void DeleteAllEntries();
|
|
|
|
/**
|
|
* @defgroup EntryListenerFunctions Entry Listener Functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Add a listener for all entries starting with a certain prefix.
|
|
*
|
|
* @param prefix UTF-8 string prefix
|
|
* @param callback listener to add
|
|
* @param flags EntryListenerFlags bitmask
|
|
* @return Listener handle
|
|
*/
|
|
NT_EntryListener AddEntryListener(
|
|
const Twine& prefix,
|
|
std::function<void(const EntryNotification& event)> callback,
|
|
unsigned int flags) const;
|
|
|
|
/**
|
|
* Remove an entry listener.
|
|
* @param entry_listener Listener handle to remove
|
|
*/
|
|
static void RemoveEntryListener(NT_EntryListener entry_listener);
|
|
|
|
/**
|
|
* Wait for the entry listener queue to be empty. This is primarily useful
|
|
* for deterministic testing. This blocks until either the entry listener
|
|
* queue is empty (e.g. there are no more events that need to be passed along
|
|
* to callbacks or poll queues) or the timeout expires.
|
|
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
|
|
* or a negative value to block indefinitely
|
|
* @return False if timed out, otherwise true.
|
|
*/
|
|
bool WaitForEntryListenerQueue(double timeout);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup ConnectionListenerFunctions Connection Listener Functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Add a connection listener.
|
|
*
|
|
* @param callback listener to add
|
|
* @param immediate_notify notify listener of all existing connections
|
|
* @return Listener handle
|
|
*/
|
|
NT_ConnectionListener AddConnectionListener(
|
|
std::function<void(const ConnectionNotification& event)> callback,
|
|
bool immediate_notify) const;
|
|
|
|
/**
|
|
* Remove a connection listener.
|
|
* @param conn_listener Listener handle to remove
|
|
*/
|
|
static void RemoveConnectionListener(NT_ConnectionListener conn_listener);
|
|
|
|
/**
|
|
* Wait for the connection listener queue to be empty. This is primarily
|
|
* useful
|
|
* for deterministic testing. This blocks until either the connection
|
|
* listener
|
|
* queue is empty (e.g. there are no more events that need to be passed along
|
|
* to callbacks or poll queues) or the timeout expires.
|
|
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
|
|
* or a negative value to block indefinitely
|
|
* @return False if timed out, otherwise true.
|
|
*/
|
|
bool WaitForConnectionListenerQueue(double timeout);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup RpcFunctions Remote Procedure Call Functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Wait for the incoming RPC call queue to be empty. This is primarily useful
|
|
* for deterministic testing. This blocks until either the RPC call
|
|
* queue is empty (e.g. there are no more events that need to be passed along
|
|
* to callbacks or poll queues) or the timeout expires.
|
|
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
|
|
* or a negative value to block indefinitely
|
|
* @return False if timed out, otherwise true.
|
|
*/
|
|
bool WaitForRpcCallQueue(double timeout);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup NetworkFunctions Client/Server Functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Set the network identity of this node.
|
|
* This is the name used during the initial connection handshake, and is
|
|
* visible through ConnectionInfo on the remote node.
|
|
* @param name identity to advertise
|
|
*/
|
|
void SetNetworkIdentity(const Twine& name);
|
|
|
|
/**
|
|
* Get the current network mode.
|
|
* @return Bitmask of NetworkMode.
|
|
*/
|
|
unsigned int GetNetworkMode() const;
|
|
|
|
/**
|
|
* Starts a server using the specified filename, listening address, and port.
|
|
*
|
|
* @param persist_filename the name of the persist file to use (UTF-8 string,
|
|
* null terminated)
|
|
* @param listen_address the address to listen on, or null to listen on any
|
|
* address (UTF-8 string, null terminated)
|
|
* @param port port to communicate over
|
|
*/
|
|
void StartServer(const Twine& persist_filename = "networktables.ini",
|
|
const char* listen_address = "",
|
|
unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Stops the server if it is running.
|
|
*/
|
|
void StopServer();
|
|
|
|
/**
|
|
* Starts a client. Use SetServer to set the server name and port.
|
|
*/
|
|
void StartClient();
|
|
|
|
/**
|
|
* Starts a client using the specified server and port
|
|
*
|
|
* @param server_name server name (UTF-8 string, null terminated)
|
|
* @param port port to communicate over
|
|
*/
|
|
void StartClient(const char* server_name, unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Starts a client using the specified (server, port) combinations. The
|
|
* client will attempt to connect to each server in round robin fashion.
|
|
*
|
|
* @param servers array of server name and port pairs
|
|
*/
|
|
void StartClient(ArrayRef<std::pair<StringRef, unsigned int>> servers);
|
|
|
|
/**
|
|
* Starts a client using the specified servers and port. The
|
|
* client will attempt to connect to each server in round robin fashion.
|
|
*
|
|
* @param servers array of server names
|
|
* @param port port to communicate over
|
|
*/
|
|
void StartClient(ArrayRef<StringRef> servers,
|
|
unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Starts a client using commonly known robot addresses for the specified
|
|
* team.
|
|
*
|
|
* @param team team number
|
|
* @param port port to communicate over
|
|
*/
|
|
void StartClientTeam(unsigned int team, unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Stops the client if it is running.
|
|
*/
|
|
void StopClient();
|
|
|
|
/**
|
|
* Sets server address and port for client (without restarting client).
|
|
*
|
|
* @param server_name server name (UTF-8 string, null terminated)
|
|
* @param port port to communicate over
|
|
*/
|
|
void SetServer(const char* server_name, unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Sets server addresses and ports for client (without restarting client).
|
|
* The client will attempt to connect to each server in round robin fashion.
|
|
*
|
|
* @param servers array of server name and port pairs
|
|
*/
|
|
void SetServer(ArrayRef<std::pair<StringRef, unsigned int>> servers);
|
|
|
|
/**
|
|
* Sets server addresses and port for client (without restarting client).
|
|
* The client will attempt to connect to each server in round robin fashion.
|
|
*
|
|
* @param servers array of server names
|
|
* @param port port to communicate over
|
|
*/
|
|
void SetServer(ArrayRef<StringRef> servers, unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Sets server addresses and port for client (without restarting client).
|
|
* Connects using commonly known robot addresses for the specified team.
|
|
*
|
|
* @param team team number
|
|
* @param port port to communicate over
|
|
*/
|
|
void SetServerTeam(unsigned int team, unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Starts requesting server address from Driver Station.
|
|
* This connects to the Driver Station running on localhost to obtain the
|
|
* server IP address.
|
|
*
|
|
* @param port server port to use in combination with IP from DS
|
|
*/
|
|
void StartDSClient(unsigned int port = kDefaultPort);
|
|
|
|
/**
|
|
* Stops requesting server address from Driver Station.
|
|
*/
|
|
void StopDSClient();
|
|
|
|
/**
|
|
* Set the periodic update rate.
|
|
* Sets how frequently updates are sent to other nodes over the network.
|
|
*
|
|
* @param interval update interval in seconds (range 0.01 to 1.0)
|
|
*/
|
|
void SetUpdateRate(double interval);
|
|
|
|
/**
|
|
* Flushes all updated values immediately to the network.
|
|
* @note This is rate-limited to protect the network from flooding.
|
|
* This is primarily useful for synchronizing network updates with
|
|
* user code.
|
|
*/
|
|
void Flush() const;
|
|
|
|
/**
|
|
* Get information on the currently established network connections.
|
|
* If operating as a client, this will return either zero or one values.
|
|
* @return array of connection information
|
|
*/
|
|
std::vector<ConnectionInfo> GetConnections() const;
|
|
|
|
/**
|
|
* Return whether or not the instance is connected to another node.
|
|
* @return True if connected.
|
|
*/
|
|
bool IsConnected() const;
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup FileFunctions File Save/Load Functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Save persistent values to a file. The server automatically does this,
|
|
* but this function provides a way to save persistent values in the same
|
|
* format to a file on either a client or a server.
|
|
* @param filename filename
|
|
* @return error string, or nullptr if successful
|
|
*/
|
|
const char* SavePersistent(const Twine& filename) const;
|
|
|
|
/**
|
|
* Load persistent values from a file. The server automatically does this
|
|
* at startup, but this function provides a way to restore persistent values
|
|
* in the same format from a file at any time on either a client or a server.
|
|
* @param filename filename
|
|
* @param warn callback function for warnings
|
|
* @return error string, or nullptr if successful
|
|
*/
|
|
const char* LoadPersistent(
|
|
const Twine& filename,
|
|
std::function<void(size_t line, const char* msg)> warn);
|
|
|
|
/**
|
|
* Save table values to a file. The file format used is identical to
|
|
* that used for SavePersistent.
|
|
* @param filename filename
|
|
* @param prefix save only keys starting with this prefix
|
|
* @return error string, or nullptr if successful
|
|
*/
|
|
const char* SaveEntries(const Twine& filename, const Twine& prefix) const;
|
|
|
|
/**
|
|
* Load table values from a file. The file format used is identical to
|
|
* that used for SavePersistent / LoadPersistent.
|
|
* @param filename filename
|
|
* @param prefix load only keys starting with this prefix
|
|
* @param warn callback function for warnings
|
|
* @return error string, or nullptr if successful
|
|
*/
|
|
const char* LoadEntries(
|
|
const Twine& filename, const Twine& prefix,
|
|
std::function<void(size_t line, const char* msg)> warn);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup LoggerFunctions Logger Functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Add logger callback function. By default, log messages are sent to stderr;
|
|
* this function sends log messages with the specified levels to the provided
|
|
* callback function instead. The callback function will only be called for
|
|
* log messages with level greater than or equal to minLevel and less than or
|
|
* equal to maxLevel; messages outside this range will be silently ignored.
|
|
*
|
|
* @param func log callback function
|
|
* @param minLevel minimum log level
|
|
* @param maxLevel maximum log level
|
|
* @return Logger handle
|
|
*/
|
|
NT_Logger AddLogger(std::function<void(const LogMessage& msg)> func,
|
|
unsigned int min_level, unsigned int max_level);
|
|
|
|
/**
|
|
* Remove a logger.
|
|
* @param logger Logger handle to remove
|
|
*/
|
|
static void RemoveLogger(NT_Logger logger);
|
|
|
|
/**
|
|
* Wait for the incoming log event queue to be empty. This is primarily
|
|
* useful
|
|
* for deterministic testing. This blocks until either the log event
|
|
* queue is empty (e.g. there are no more events that need to be passed along
|
|
* to callbacks or poll queues) or the timeout expires.
|
|
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
|
|
* or a negative value to block indefinitely
|
|
* @return False if timed out, otherwise true.
|
|
*/
|
|
bool WaitForLoggerQueue(double timeout);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
* Equality operator. Returns true if both instances refer to the same
|
|
* native handle.
|
|
*/
|
|
bool operator==(const NetworkTableInstance& other) const {
|
|
return m_handle == other.m_handle;
|
|
}
|
|
|
|
/** Inequality operator. */
|
|
bool operator!=(const NetworkTableInstance& other) const {
|
|
return !(*this == other);
|
|
}
|
|
|
|
private:
|
|
/* Native handle */
|
|
NT_Inst m_handle;
|
|
};
|
|
|
|
} // namespace nt
|
|
|
|
#include "networktables/NetworkTableInstance.inl"
|
|
|
|
#endif // NTCORE_NETWORKTABLES_NETWORKTABLEINSTANCE_H_
|