WPILibC++  2019.3.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
nt::NetworkTableInstance Class Referencefinal

NetworkTables Instance. More...

#include <NetworkTableInstance.h>

Public Types

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
}
 Client/server mode flag values (as returned by GetNetworkMode()). More...
 
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
}
 Logging levels (as used by SetLogger()).
 
enum  { kDefaultPort = NT_DEFAULT_PORT }
 The default port that network tables operates on.
 

Public Member Functions

 NetworkTableInstance () noexcept
 Construct invalid instance.
 
 NetworkTableInstance (NT_Inst inst) noexcept
 Construct from native handle. More...
 
 operator bool () const
 Determines if the native handle is valid. More...
 
NT_Inst GetHandle () const
 Gets the native handle for the entry. More...
 
NetworkTableEntry GetEntry (const Twine &name)
 Gets the entry for a key. More...
 
std::vector< NetworkTableEntryGetEntries (const Twine &prefix, unsigned int types)
 Get entries starting with the given prefix. More...
 
std::vector< EntryInfoGetEntryInfo (const Twine &prefix, unsigned int types) const
 Get information about entries starting with the given prefix. More...
 
std::shared_ptr< NetworkTableGetTable (const Twine &key) const
 Gets the table with the specified key. More...
 
void DeleteAllEntries ()
 Deletes ALL keys in ALL subtables (except persistent values). More...
 
bool operator== (const NetworkTableInstance &other) const
 Equality operator. More...
 
bool operator!= (const NetworkTableInstance &other) const
 Inequality operator. More...
 
Remote Procedure Call Functions
bool WaitForRpcCallQueue (double timeout)
 Wait for the incoming RPC call queue to be empty. More...
 
Client/Server Functions
void SetNetworkIdentity (const Twine &name)
 Set the network identity of this node. More...
 
unsigned int GetNetworkMode () const
 Get the current network mode. More...
 
void StartServer (const Twine &persist_filename="networktables.ini", const char *listen_address="", unsigned int port=kDefaultPort)
 Starts a server using the specified filename, listening address, and port. More...
 
void StopServer ()
 Stops the server if it is running.
 
void StartClient ()
 Starts a client. More...
 
void StartClient (const char *server_name, unsigned int port=kDefaultPort)
 Starts a client using the specified server and port. More...
 
void StartClient (ArrayRef< std::pair< StringRef, unsigned int >> servers)
 Starts a client using the specified (server, port) combinations. More...
 
void StartClient (ArrayRef< StringRef > servers, unsigned int port=kDefaultPort)
 Starts a client using the specified servers and port. More...
 
void StartClientTeam (unsigned int team, unsigned int port=kDefaultPort)
 Starts a client using commonly known robot addresses for the specified team. More...
 
void StopClient ()
 Stops the client if it is running.
 
void SetServer (const char *server_name, unsigned int port=kDefaultPort)
 Sets server address and port for client (without restarting client). More...
 
void SetServer (ArrayRef< std::pair< StringRef, unsigned int >> servers)
 Sets server addresses and ports for client (without restarting client). More...
 
void SetServer (ArrayRef< StringRef > servers, unsigned int port=kDefaultPort)
 Sets server addresses and port for client (without restarting client). More...
 
void SetServerTeam (unsigned int team, unsigned int port=kDefaultPort)
 Sets server addresses and port for client (without restarting client). More...
 
void StartDSClient (unsigned int port=kDefaultPort)
 Starts requesting server address from Driver Station. More...
 
void StopDSClient ()
 Stops requesting server address from Driver Station.
 
void SetUpdateRate (double interval)
 Set the periodic update rate. More...
 
void Flush () const
 Flushes all updated values immediately to the network. More...
 
std::vector< ConnectionInfoGetConnections () const
 Get information on the currently established network connections. More...
 
bool IsConnected () const
 Return whether or not the instance is connected to another node. More...
 
File Save/Load Functions
const char * SavePersistent (const Twine &filename) const
 Save persistent values to a file. More...
 
const char * LoadPersistent (const Twine &filename, std::function< void(size_t line, const char *msg)> warn)
 Load persistent values from a file. More...
 
const char * SaveEntries (const Twine &filename, const Twine &prefix) const
 Save table values to a file. More...
 
const char * LoadEntries (const Twine &filename, const Twine &prefix, std::function< void(size_t line, const char *msg)> warn)
 Load table values from a file. More...
 

Static Public Member Functions

static NetworkTableInstance GetDefault ()
 Get global default instance. More...
 
static NetworkTableInstance Create ()
 Create an instance. More...
 
static void Destroy (NetworkTableInstance inst)
 Destroys an instance (note: this has global effect). More...
 

Entry Listener Functions

NT_EntryListener AddEntryListener (const Twine &prefix, std::function< void(const EntryNotification &event)> callback, unsigned int flags) const
 Add a listener for all entries starting with a certain prefix. More...
 
bool WaitForEntryListenerQueue (double timeout)
 Wait for the entry listener queue to be empty. More...
 
static void RemoveEntryListener (NT_EntryListener entry_listener)
 Remove an entry listener. More...
 

Connection Listener Functions

NT_ConnectionListener AddConnectionListener (std::function< void(const ConnectionNotification &event)> callback, bool immediate_notify) const
 Add a connection listener. More...
 
bool WaitForConnectionListenerQueue (double timeout)
 Wait for the connection listener queue to be empty. More...
 
static void RemoveConnectionListener (NT_ConnectionListener conn_listener)
 Remove a connection listener. More...
 

Logger Functions

NT_Logger AddLogger (std::function< void(const LogMessage &msg)> func, unsigned int min_level, unsigned int max_level)
 Add logger callback function. More...
 
bool WaitForLoggerQueue (double timeout)
 Wait for the incoming log event queue to be empty. More...
 
static void RemoveLogger (NT_Logger logger)
 Remove a logger. More...
 

Detailed Description

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()).

Constructor & Destructor Documentation

nt::NetworkTableInstance::NetworkTableInstance ( NT_Inst  inst)
inlineexplicitnoexcept

Construct from native handle.

Parameters
handleNative handle

Member Function Documentation

NT_ConnectionListener nt::NetworkTableInstance::AddConnectionListener ( std::function< void(const ConnectionNotification &event)>  callback,
bool  immediate_notify 
) const

Add a connection listener.

Parameters
callbacklistener to add
immediate_notifynotify listener of all existing connections
Returns
Listener handle
NT_EntryListener nt::NetworkTableInstance::AddEntryListener ( const Twine prefix,
std::function< void(const EntryNotification &event)>  callback,
unsigned int  flags 
) const

Add a listener for all entries starting with a certain prefix.

Parameters
prefixUTF-8 string prefix
callbacklistener to add
flagsEntryListenerFlags bitmask
Returns
Listener handle
NT_Logger nt::NetworkTableInstance::AddLogger ( std::function< void(const LogMessage &msg)>  func,
unsigned int  min_level,
unsigned int  max_level 
)
inline

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.

Parameters
funclog callback function
minLevelminimum log level
maxLevelmaximum log level
Returns
Logger handle
NetworkTableInstance nt::NetworkTableInstance::Create ( )
inlinestatic

Create an instance.

Returns
Newly created instance
void nt::NetworkTableInstance::DeleteAllEntries ( )
inline

Deletes ALL keys in ALL subtables (except persistent values).

Use with caution!

void nt::NetworkTableInstance::Destroy ( NetworkTableInstance  inst)
inlinestatic

Destroys an instance (note: this has global effect).

Parameters
instInstance
void nt::NetworkTableInstance::Flush ( ) const
inline

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.
std::vector< ConnectionInfo > nt::NetworkTableInstance::GetConnections ( ) const
inline

Get information on the currently established network connections.

If operating as a client, this will return either zero or one values.

Returns
array of connection information
NetworkTableInstance nt::NetworkTableInstance::GetDefault ( )
inlinestatic

Get global default instance.

Returns
Global default instance
std::vector< NetworkTableEntry > nt::NetworkTableInstance::GetEntries ( const Twine prefix,
unsigned int  types 
)
inline

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.

Parameters
prefixentry name required prefix; only entries whose name starts with this string are returned
typesbitmask of types; 0 is treated as a "don't care"
Returns
Array of entries.
NetworkTableEntry nt::NetworkTableInstance::GetEntry ( const Twine name)
inline

Gets the entry for a key.

Parameters
nameKey
Returns
Network table entry.
std::vector< EntryInfo > nt::NetworkTableInstance::GetEntryInfo ( const Twine prefix,
unsigned int  types 
) const
inline

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.

Parameters
prefixentry name required prefix; only entries whose name starts with this string are returned
typesbitmask of types; 0 is treated as a "don't care"
Returns
Array of entry information.
NT_Inst nt::NetworkTableInstance::GetHandle ( ) const
inline

Gets the native handle for the entry.

Returns
Native handle
unsigned int nt::NetworkTableInstance::GetNetworkMode ( ) const
inline

Get the current network mode.

Returns
Bitmask of NetworkMode.
std::shared_ptr<NetworkTable> nt::NetworkTableInstance::GetTable ( const Twine key) const

Gets the table with the specified key.

Parameters
keythe key name
Returns
The network table
bool nt::NetworkTableInstance::IsConnected ( ) const
inline

Return whether or not the instance is connected to another node.

Returns
True if connected.
const char * nt::NetworkTableInstance::LoadEntries ( const Twine filename,
const Twine prefix,
std::function< void(size_t line, const char *msg)>  warn 
)
inline

Load table values from a file.

The file format used is identical to that used for SavePersistent / LoadPersistent.

Parameters
filenamefilename
prefixload only keys starting with this prefix
warncallback function for warnings
Returns
error string, or nullptr if successful
const char * nt::NetworkTableInstance::LoadPersistent ( const Twine filename,
std::function< void(size_t line, const char *msg)>  warn 
)
inline

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.

Parameters
filenamefilename
warncallback function for warnings
Returns
error string, or nullptr if successful
nt::NetworkTableInstance::operator bool ( ) const
inlineexplicit

Determines if the native handle is valid.

Returns
True if the native handle is valid, false otherwise.
bool nt::NetworkTableInstance::operator!= ( const NetworkTableInstance other) const
inline

Inequality operator.

bool nt::NetworkTableInstance::operator== ( const NetworkTableInstance other) const
inline

Equality operator.

Returns true if both instances refer to the same native handle.

void nt::NetworkTableInstance::RemoveConnectionListener ( NT_ConnectionListener  conn_listener)
inlinestatic

Remove a connection listener.

Parameters
conn_listenerListener handle to remove
void nt::NetworkTableInstance::RemoveEntryListener ( NT_EntryListener  entry_listener)
inlinestatic

Remove an entry listener.

Parameters
entry_listenerListener handle to remove
void nt::NetworkTableInstance::RemoveLogger ( NT_Logger  logger)
inlinestatic

Remove a logger.

Parameters
loggerLogger handle to remove
const char * nt::NetworkTableInstance::SaveEntries ( const Twine filename,
const Twine prefix 
) const
inline

Save table values to a file.

The file format used is identical to that used for SavePersistent.

Parameters
filenamefilename
prefixsave only keys starting with this prefix
Returns
error string, or nullptr if successful
const char * nt::NetworkTableInstance::SavePersistent ( const Twine filename) const
inline

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.

Parameters
filenamefilename
Returns
error string, or nullptr if successful
void nt::NetworkTableInstance::SetNetworkIdentity ( const Twine name)
inline

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.

Parameters
nameidentity to advertise
void nt::NetworkTableInstance::SetServer ( const char *  server_name,
unsigned int  port = kDefaultPort 
)
inline

Sets server address and port for client (without restarting client).

Parameters
server_nameserver name (UTF-8 string, null terminated)
portport to communicate over
void nt::NetworkTableInstance::SetServer ( ArrayRef< std::pair< StringRef, unsigned int >>  servers)
inline

Sets server addresses and ports for client (without restarting client).

The client will attempt to connect to each server in round robin fashion.

Parameters
serversarray of server name and port pairs
void nt::NetworkTableInstance::SetServer ( ArrayRef< StringRef servers,
unsigned int  port = kDefaultPort 
)

Sets server addresses and port for client (without restarting client).

The client will attempt to connect to each server in round robin fashion.

Parameters
serversarray of server names
portport to communicate over
void nt::NetworkTableInstance::SetServerTeam ( unsigned int  team,
unsigned int  port = kDefaultPort 
)
inline

Sets server addresses and port for client (without restarting client).

Connects using commonly known robot addresses for the specified team.

Parameters
teamteam number
portport to communicate over
void nt::NetworkTableInstance::SetUpdateRate ( double  interval)
inline

Set the periodic update rate.

Sets how frequently updates are sent to other nodes over the network.

Parameters
intervalupdate interval in seconds (range 0.01 to 1.0)
void nt::NetworkTableInstance::StartClient ( )
inline

Starts a client.

Use SetServer to set the server name and port.

void nt::NetworkTableInstance::StartClient ( const char *  server_name,
unsigned int  port = kDefaultPort 
)
inline

Starts a client using the specified server and port.

Parameters
server_nameserver name (UTF-8 string, null terminated)
portport to communicate over
void nt::NetworkTableInstance::StartClient ( ArrayRef< std::pair< StringRef, unsigned int >>  servers)
inline

Starts a client using the specified (server, port) combinations.

The client will attempt to connect to each server in round robin fashion.

Parameters
serversarray of server name and port pairs
void nt::NetworkTableInstance::StartClient ( ArrayRef< StringRef servers,
unsigned int  port = kDefaultPort 
)

Starts a client using the specified servers and port.

The client will attempt to connect to each server in round robin fashion.

Parameters
serversarray of server names
portport to communicate over
void nt::NetworkTableInstance::StartClientTeam ( unsigned int  team,
unsigned int  port = kDefaultPort 
)
inline

Starts a client using commonly known robot addresses for the specified team.

Parameters
teamteam number
portport to communicate over
void nt::NetworkTableInstance::StartDSClient ( unsigned int  port = kDefaultPort)
inline

Starts requesting server address from Driver Station.

This connects to the Driver Station running on localhost to obtain the server IP address.

Parameters
portserver port to use in combination with IP from DS
void nt::NetworkTableInstance::StartServer ( const Twine persist_filename = "networktables.ini",
const char *  listen_address = "",
unsigned int  port = kDefaultPort 
)
inline

Starts a server using the specified filename, listening address, and port.

Parameters
persist_filenamethe name of the persist file to use (UTF-8 string, null terminated)
listen_addressthe address to listen on, or null to listen on any address (UTF-8 string, null terminated)
portport to communicate over
bool nt::NetworkTableInstance::WaitForConnectionListenerQueue ( double  timeout)
inline

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.

Parameters
timeouttimeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
Returns
False if timed out, otherwise true.
bool nt::NetworkTableInstance::WaitForEntryListenerQueue ( double  timeout)
inline

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.

Parameters
timeouttimeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
Returns
False if timed out, otherwise true.
bool nt::NetworkTableInstance::WaitForLoggerQueue ( double  timeout)
inline

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.

Parameters
timeouttimeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
Returns
False if timed out, otherwise true.
bool nt::NetworkTableInstance::WaitForRpcCallQueue ( double  timeout)
inline

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.

Parameters
timeouttimeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
Returns
False if timed out, otherwise true.

The documentation for this class was generated from the following files: