Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-19 00:41:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

ntcore: Documentation cleanups (#1237)

Browse Source
This commit is contained in:
Peter Johnson
2018-07-28 17:41:57 -07:00
committed by GitHub
parent f2393feeef
commit 186e1dc54b
22 changed files with 607 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
ntcore/src/main/java/edu/wpi/first/networktables/ConnectionInfo.java
View File

@@ -46,6 +46,7 @@ public final class ConnectionInfo {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param remoteId Remote identifier
* @param remoteIp Remote IP address
* @param remotePort Remote port number

1
ntcore/src/main/java/edu/wpi/first/networktables/ConnectionNotification.java
View File

@@ -31,6 +31,7 @@ public final class ConnectionNotification {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param inst Instance
* @param listener Listener that was triggered
* @param connected Connected if true

2
ntcore/src/main/java/edu/wpi/first/networktables/EntryInfo.java
View File

@@ -33,6 +33,7 @@ public final class EntryInfo {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param inst Instance
* @param entry Entry handle
* @param name Name
@@ -58,6 +59,7 @@ public final class EntryInfo {
/**
* Get the entry as an object.
*
* @return NetworkTableEntry for this entry.
*/
NetworkTableEntry getEntry() {

2
ntcore/src/main/java/edu/wpi/first/networktables/EntryNotification.java
View File

@@ -44,6 +44,7 @@ public final class EntryNotification {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param inst Instance
* @param listener Listener that was triggered
* @param entry Entry handle
@@ -69,6 +70,7 @@ public final class EntryNotification {
/**
* Get the entry as an object.
*
* @return NetworkTableEntry for this entry.
*/
public NetworkTableEntry getEntry() {

1
ntcore/src/main/java/edu/wpi/first/networktables/LogMessage.java
View File

@@ -56,6 +56,7 @@ public final class LogMessage {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param inst Instance
* @param logger Logger
* @param level Log level

16
ntcore/src/main/java/edu/wpi/first/networktables/NetworkTable.java
View File

@@ -22,7 +22,6 @@ import java.util.function.Consumer;
public final class NetworkTable {
/**
* The path separator for sub-tables and keys.
*
*/
public static final char PATH_SEPARATOR = '/';
@@ -33,6 +32,7 @@ public final class NetworkTable {
/**
* Gets the "base name" of a key. For example, "/foo/bar" becomes "bar".
* If the key has a trailing slash, returns an empty string.
*
* @param key key
* @return base name
*/
@@ -95,6 +95,7 @@ public final class NetworkTable {
* Gets a list of the names of all the super tables of a given key. For
* example, the key "/foo/bar/baz" has a hierarchy of "/", "/foo",
* "/foo/bar", and "/foo/bar/baz".
*
* @param key the key
* @return List of super tables
*/
@@ -128,6 +129,7 @@ public final class NetworkTable {
/**
* Gets the instance for the table.
*
* @return Instance
*/
public NetworkTableInstance getInstance() {
@@ -143,6 +145,7 @@ public final class NetworkTable {
/**
* Gets the entry for a sub key.
*
* @param key the key name
* @return Network table entry.
*/
@@ -157,6 +160,7 @@ public final class NetworkTable {
/**
* Listen to keys only within this table.
*
* @param listener listener to add
* @param flags {@link EntryListenerFlags} bitmask
* @return Listener handle
@@ -175,6 +179,7 @@ public final class NetworkTable {
/**
* Listen to a single key.
*
* @param key the key name
* @param listener listener to add
* @param flags {@link EntryListenerFlags} bitmask
@@ -188,6 +193,7 @@ public final class NetworkTable {
/**
* Remove an entry listener.
*
* @param listener listener handle
*/
public void removeEntryListener(int listener) {
@@ -198,6 +204,7 @@ public final class NetworkTable {
* Listen for sub-table creation.
* This calls the listener once for each newly created sub-table.
* It immediately calls the listener for any existing sub-tables.
*
* @param listener listener to add
* @param localNotify notify local changes as well as remote
* @return Listener handle
@@ -233,6 +240,7 @@ public final class NetworkTable {
/**
* Remove a sub-table listener.
*
* @param listener listener handle
*/
public void removeTableListener(int listener) {
@@ -275,6 +283,7 @@ public final class NetworkTable {
/**
* Gets all keys in the table (not including sub-tables).
*
* @param types bitmask of types; 0 is treated as a "don't care".
* @return keys currently in the table
*/
@@ -297,6 +306,7 @@ public final class NetworkTable {
/**
* Gets all keys in the table (not including sub-tables).
*
* @return keys currently in the table
*/
public Set<String> getKeys() {
@@ -305,6 +315,7 @@ public final class NetworkTable {
/**
* Gets the names of all subtables in the table.
*
* @return subtables currently in the table
*/
public Set<String> getSubTables() {
@@ -344,6 +355,7 @@ public final class NetworkTable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
@@ -372,6 +384,7 @@ public final class NetworkTable {
/**
* Save table values to a file. The file format used is identical to
* that used for SavePersistent.
*
* @param filename filename
* @throws PersistentException if error saving file
*/
@@ -382,6 +395,7 @@ public final class NetworkTable {
/**
* Load table values from a file. The file format used is identical to
* that used for SavePersistent / LoadPersistent.
*
* @param filename filename
* @return List of warnings (errors result in an exception instead)
* @throws PersistentException if error saving file

63
ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableEntry.java
View File

@@ -21,6 +21,7 @@ public final class NetworkTableEntry {
/**
* Construct from native handle.
*
* @param inst Instance
* @param handle Native handle
*/
@@ -31,6 +32,7 @@ public final class NetworkTableEntry {
/**
* Determines if the native handle is valid.
*
* @return True if the native handle is valid, false otherwise.
*/
public boolean isValid() {
@@ -39,6 +41,7 @@ public final class NetworkTableEntry {
/**
* Gets the native handle for the entry.
*
* @return Native handle
*/
public int getHandle() {
@@ -47,6 +50,7 @@ public final class NetworkTableEntry {
/**
* Gets the instance for the entry.
*
* @return Instance
*/
public NetworkTableInstance getInstance() {
@@ -55,6 +59,7 @@ public final class NetworkTableEntry {
/**
* Determines if the entry currently exists.
*
* @return True if the entry exists, false otherwise.
*/
public boolean exists() {
@@ -63,6 +68,7 @@ public final class NetworkTableEntry {
/**
* Gets the name of the entry (the key).
*
* @return the entry's name
*/
public String getName() {
@@ -71,6 +77,7 @@ public final class NetworkTableEntry {
/**
* Gets the type of the entry.
*
* @return the entry's type
*/
public NetworkTableType getType() {
@@ -79,6 +86,7 @@ public final class NetworkTableEntry {
/**
* Returns the flags.
*
* @return the flags (bitmask)
*/
public int getFlags() {
@@ -87,6 +95,7 @@ public final class NetworkTableEntry {
/**
* Gets the last time the entry's value was changed.
*
* @return Entry last change time
*/
public long getLastChange() {
@@ -95,6 +104,7 @@ public final class NetworkTableEntry {
/**
* Gets combined information about the entry.
*
* @return Entry information
*/
public EntryInfo getInfo() {
@@ -105,6 +115,7 @@ public final class NetworkTableEntry {
* Gets the entry's value.
* Returns a value with type NetworkTableType.kUnassigned if the value
* does not exist.
*
* @return the entry's value
*/
public NetworkTableValue getValue() {
@@ -114,6 +125,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a boolean. If the entry does not exist or is of
* different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -124,6 +136,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a double. If the entry does not exist or is of
* different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -134,6 +147,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a double. If the entry does not exist or is of
* different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -144,6 +158,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a string. If the entry does not exist or is of
* different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -154,6 +169,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a raw value (byte array). If the entry does not
* exist or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -164,6 +180,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a boolean array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -174,6 +191,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a boolean array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -185,6 +203,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a double array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -195,6 +214,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a double array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -206,6 +226,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a double array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -217,6 +238,7 @@ public final class NetworkTableEntry {
/**
* Gets the entry's value as a string array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*/
@@ -226,6 +248,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
* @throws IllegalArgumentException if the value is not a known type
@@ -282,6 +305,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -291,6 +315,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -300,6 +325,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -309,6 +335,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -318,6 +345,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -327,6 +355,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -336,6 +365,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -346,6 +376,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -355,6 +386,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -365,6 +397,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -374,6 +407,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value that will be assigned
* @return False if the table key already exists with a different type
* @throws IllegalArgumentException if the value is not a known type
@@ -430,6 +464,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -439,6 +474,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -448,6 +484,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -457,6 +494,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -466,6 +504,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -475,6 +514,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @param len the length of the value
* @return False if the entry exists with a different type
@@ -491,6 +531,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -500,6 +541,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -509,6 +551,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -518,6 +561,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -527,6 +571,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -537,6 +582,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
* @throws IllegalArgumentException if the value is not a known type
*/
@@ -598,6 +644,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetBoolean(boolean value) {
@@ -607,6 +654,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetDouble(double value) {
@@ -616,6 +664,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetNumber(Number value) {
@@ -625,6 +674,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetString(String value) {
@@ -634,6 +684,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetRaw(byte[] value) {
@@ -643,6 +694,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetBooleanArray(boolean[] value) {
@@ -652,6 +704,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetBooleanArray(Boolean[] value) {
@@ -661,6 +714,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetDoubleArray(double[] value) {
@@ -670,6 +724,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetNumberArray(Number[] value) {
@@ -679,6 +734,7 @@ public final class NetworkTableEntry {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
public void forceSetStringArray(String[] value) {
@@ -687,6 +743,7 @@ public final class NetworkTableEntry {
/**
* Sets flags.
*
* @param flags the flags to set (bitmask)
*/
public void setFlags(int flags) {
@@ -695,6 +752,7 @@ public final class NetworkTableEntry {
/**
* Clears flags.
*
* @param flags the flags to clear (bitmask)
*/
public void clearFlags(int flags) {
@@ -717,6 +775,7 @@ public final class NetworkTableEntry {
/**
* Returns whether the value is persistent through program restarts.
*
* @return True if the value is persistent.
*/
public boolean isPersistent() {
@@ -734,6 +793,7 @@ public final class NetworkTableEntry {
* Create a callback-based RPC entry point. Only valid to use on the server.
* The callback function will be called when the RPC is called.
* This function creates RPC version 0 definitions (raw data in and out).
*
* @param callback callback function
*/
void createRpc(Consumer<RpcAnswer> callback) {
@@ -745,6 +805,7 @@ public final class NetworkTableEntry {
* This function is non-blocking. Either {@link RpcCall#getResult()} or
* {@link RpcCall#cancelResult()} must be called on the return value to either
* get or ignore the result of the call.
*
* @param params parameter
* @return RPC call object.
*/
@@ -754,6 +815,7 @@ public final class NetworkTableEntry {
/**
* Add a listener for changes to the entry.
*
* @param listener the listener to add
* @param flags bitmask specifying desired notifications
* @return listener handle
@@ -764,6 +826,7 @@ public final class NetworkTableEntry {
/**
* Remove a listener from receiving entry events.
*
* @param listener the listener to be removed
*/
public void removeListener(int listener) {

20
ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableInstance.java
View File

@@ -52,6 +52,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Construct from native handle.
*
* @param handle Native handle
*/
private NetworkTableInstance(int handle) {
@@ -76,6 +77,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Determines if the native handle is valid.
*
* @return True if the native handle is valid, false otherwise.
*/
public boolean isValid() {
@@ -87,6 +89,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Get global default instance.
*
* @return Global default instance
*/
public static synchronized NetworkTableInstance getDefault() {
@@ -100,6 +103,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* Create an instance.
* Note: A reference to the returned instance must be retained to ensure the
* instance is not garbage collected.
*
* @return Newly created instance
*/
public static NetworkTableInstance create() {
@@ -110,6 +114,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Gets the native handle for the entry.
*
* @return Native handle
*/
public int getHandle() {
@@ -118,6 +123,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Gets the entry for a key.
*
* @param name Key
* @return Network table entry.
*/
@@ -330,6 +336,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Remove an entry listener.
*
* @param listener Listener handle to remove
*/
public void removeEntryListener(int listener) {
@@ -341,6 +348,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* 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.
@@ -465,6 +473,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Remove a connection listener.
*
* @param listener Listener handle to remove
*/
public void removeConnectionListener(int listener) {
@@ -482,6 +491,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* 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.
@@ -590,6 +600,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* Create a callback-based RPC entry point. Only valid to use on the server.
* The callback function will be called when the RPC is called.
* This function creates RPC version 0 definitions (raw data in and out).
*
* @param entry the entry
* @param callback callback function
*/
@@ -612,6 +623,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* 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.
@@ -652,6 +664,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* 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
*/
public void setNetworkIdentity(String name) {
@@ -660,6 +673,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Get the current network mode.
*
* @return Bitmask of NetworkMode.
*/
public int getNetworkMode() {
@@ -934,6 +948,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Gets 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
*/
public ConnectionInfo[] getConnections() {
@@ -942,6 +957,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Return whether or not the instance is connected to another node.
*
* @return True if connected.
*/
public boolean isConnected() {
@@ -972,6 +988,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* 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
* @throws PersistentException if error saving file
@@ -983,6 +1000,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* 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
* @return List of warnings (errors result in an exception instead)
@@ -1074,6 +1092,7 @@ public final class NetworkTableInstance implements AutoCloseable {
/**
* Remove a logger.
*
* @param logger Logger handle to remove
*/
public void removeLogger(int logger) {
@@ -1091,6 +1110,7 @@ public final class NetworkTableInstance implements AutoCloseable {
* 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.

40
ntcore/src/main/java/edu/wpi/first/networktables/NetworkTableValue.java
View File

@@ -29,6 +29,7 @@ public final class NetworkTableValue {
/**
* Get the data type.
*
* @return The type.
*/
public NetworkTableType getType() {
@@ -37,6 +38,7 @@ public final class NetworkTableValue {
/**
* Get the data value stored.
*
* @return The type.
*/
public Object getValue() {
@@ -45,6 +47,7 @@ public final class NetworkTableValue {
/**
* Get the creation time of the value.
*
* @return The time, in the units returned by NetworkTablesJNI.now().
*/
public long getTime() {
@@ -57,6 +60,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a value or is unassigned.
*
* @return True if the entry value contains a value.
*/
public boolean isValid() {
@@ -65,6 +69,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a boolean.
*
* @return True if the entry value is of boolean type.
*/
public boolean isBoolean() {
@@ -73,6 +78,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a double.
*
* @return True if the entry value is of double type.
*/
public boolean isDouble() {
@@ -81,6 +87,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a string.
*
* @return True if the entry value is of string type.
*/
public boolean isString() {
@@ -89,6 +96,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a raw.
*
* @return True if the entry value is of raw type.
*/
public boolean isRaw() {
@@ -97,6 +105,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a rpc definition.
*
* @return True if the entry value is of rpc definition type.
*/
public boolean isRpc() {
@@ -105,6 +114,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a boolean array.
*
* @return True if the entry value is of boolean array type.
*/
public boolean isBooleanArray() {
@@ -113,6 +123,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a double array.
*
* @return True if the entry value is of double array type.
*/
public boolean isDoubleArray() {
@@ -121,6 +132,7 @@ public final class NetworkTableValue {
/**
* Determine if entry value contains a string array.
*
* @return True if the entry value is of string array type.
*/
public boolean isStringArray() {
@@ -133,6 +145,7 @@ public final class NetworkTableValue {
/**
* Get the entry's boolean value.
*
* @return The boolean value.
* @throws ClassCastException if the entry value is not of boolean type.
*/
@@ -145,6 +158,7 @@ public final class NetworkTableValue {
/**
* Get the entry's double value.
*
* @return The double value.
* @throws ClassCastException if the entry value is not of double type.
*/
@@ -157,6 +171,7 @@ public final class NetworkTableValue {
/**
* Get the entry's string value.
*
* @return The string value.
* @throws ClassCastException if the entry value is not of string type.
*/
@@ -169,6 +184,7 @@ public final class NetworkTableValue {
/**
* Get the entry's raw value.
*
* @return The raw value.
* @throws ClassCastException if the entry value is not of raw type.
*/
@@ -181,6 +197,7 @@ public final class NetworkTableValue {
/**
* Get the entry's rpc definition value.
*
* @return The rpc definition value.
* @throws ClassCastException if the entry value is not of rpc definition type.
*/
@@ -193,6 +210,7 @@ public final class NetworkTableValue {
/**
* Get the entry's boolean array value.
*
* @return The boolean array value.
* @throws ClassCastException if the entry value is not of boolean array type.
*/
@@ -205,6 +223,7 @@ public final class NetworkTableValue {
/**
* Get the entry's double array value.
*
* @return The double array value.
* @throws ClassCastException if the entry value is not of double array type.
*/
@@ -217,6 +236,7 @@ public final class NetworkTableValue {
/**
* Get the entry's string array value.
*
* @return The string array value.
* @throws ClassCastException if the entry value is not of string array type.
*/
@@ -233,6 +253,7 @@ public final class NetworkTableValue {
/**
* Creates a boolean entry value.
*
* @param value the value
* @return The entry value
*/
@@ -242,6 +263,7 @@ public final class NetworkTableValue {
/**
* Creates a boolean entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -252,6 +274,7 @@ public final class NetworkTableValue {
/**
* Creates a double entry value.
*
* @param value the value
* @return The entry value
*/
@@ -261,6 +284,7 @@ public final class NetworkTableValue {
/**
* Creates a double entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -271,6 +295,7 @@ public final class NetworkTableValue {
/**
* Creates a string entry value.
*
* @param value the value
* @return The entry value
*/
@@ -280,6 +305,7 @@ public final class NetworkTableValue {
/**
* Creates a string entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -290,6 +316,7 @@ public final class NetworkTableValue {
/**
* Creates a raw entry value.
*
* @param value the value
* @return The entry value
*/
@@ -299,6 +326,7 @@ public final class NetworkTableValue {
/**
* Creates a raw entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -309,6 +337,7 @@ public final class NetworkTableValue {
/**
* Creates a rpc entry value.
*
* @param value the value
* @return The entry value
*/
@@ -318,6 +347,7 @@ public final class NetworkTableValue {
/**
* Creates a rpc entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -328,6 +358,7 @@ public final class NetworkTableValue {
/**
* Creates a boolean array entry value.
*
* @param value the value
* @return The entry value
*/
@@ -337,6 +368,7 @@ public final class NetworkTableValue {
/**
* Creates a boolean array entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -347,6 +379,7 @@ public final class NetworkTableValue {
/**
* Creates a boolean array entry value.
*
* @param value the value
* @return The entry value
*/
@@ -356,6 +389,7 @@ public final class NetworkTableValue {
/**
* Creates a boolean array entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -366,6 +400,7 @@ public final class NetworkTableValue {
/**
* Creates a double array entry value.
*
* @param value the value
* @return The entry value
*/
@@ -375,6 +410,7 @@ public final class NetworkTableValue {
/**
* Creates a double array entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -385,6 +421,7 @@ public final class NetworkTableValue {
/**
* Creates a double array entry value.
*
* @param value the value
* @return The entry value
*/
@@ -394,6 +431,7 @@ public final class NetworkTableValue {
/**
* Creates a double array entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value
@@ -404,6 +442,7 @@ public final class NetworkTableValue {
/**
* Creates a string array entry value.
*
* @param value the value
* @return The entry value
*/
@@ -413,6 +452,7 @@ public final class NetworkTableValue {
/**
* Creates a string array entry value.
*
* @param value the value
* @param time the creation time to use (instead of the current time)
* @return The entry value

4
ntcore/src/main/java/edu/wpi/first/networktables/RpcAnswer.java
View File

@@ -33,6 +33,7 @@ public final class RpcAnswer {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param inst Instance
* @param entry Entry handle
* @param call Call handle
@@ -65,6 +66,7 @@ public final class RpcAnswer {
/**
* Determines if the native handle is valid.
*
* @return True if the native handle is valid, false otherwise.
*/
public boolean isValid() {
@@ -73,6 +75,7 @@ public final class RpcAnswer {
/**
* Post RPC response (return value) for a polled RPC.
*
* @param result result raw data that will be provided to remote caller
* @return true if the response was posted, otherwise false
*/
@@ -90,6 +93,7 @@ public final class RpcAnswer {
/**
* Get the entry as an object.
*
* @return NetworkTableEntry for the RPC.
*/
NetworkTableEntry getEntry() {

6
ntcore/src/main/java/edu/wpi/first/networktables/RpcCall.java
View File

@@ -13,6 +13,7 @@ package edu.wpi.first.networktables;
public final class RpcCall implements AutoCloseable {
/** Constructor.
* This should generally only be used internally to NetworkTables.
*
* @param entry Entry
* @param call Call handle
*/
@@ -38,6 +39,7 @@ public final class RpcCall implements AutoCloseable {
/**
* Determines if the native handle is valid.
*
* @return True if the native handle is valid, false otherwise.
*/
public boolean isValid() {
@@ -46,6 +48,7 @@ public final class RpcCall implements AutoCloseable {
/**
* Get the RPC entry.
*
* @return NetworkTableEntry for the RPC.
*/
public NetworkTableEntry getEntry() {
@@ -54,6 +57,7 @@ public final class RpcCall implements AutoCloseable {
/**
* Get the call native handle.
*
* @return Native handle.
*/
public int getCall() {
@@ -63,6 +67,7 @@ public final class RpcCall implements AutoCloseable {
/**
* Get the result (return value). This function blocks until
* the result is received.
*
* @return Received result (output)
*/
public byte[] getResult() {
@@ -76,6 +81,7 @@ public final class RpcCall implements AutoCloseable {
/**
* Get the result (return value). This function blocks until
* the result is received or it times out.
*
* @param timeout timeout, in seconds
* @return Received result (output)
*/

21
ntcore/src/main/native/include/networktables/EntryListenerFlags.h
View File

@@ -12,6 +12,7 @@
namespace nt {
/** Entry listener flags */
namespace EntryListenerFlags {
/**
@@ -26,15 +27,19 @@ namespace EntryListenerFlags {
* By default, notifications are only generated for remote changes occurring
* after the listener is created. The constants kImmediate and kLocal are
* modifiers that cause notifications to be generated at other times.
*
* @ingroup ntcore_cpp_api
*/
enum {
/** Initial listener addition.
/**
* Initial listener addition.
* Set this flag to receive immediate notification of entries matching the
* flag criteria (generally only useful when combined with kNew).
*/
kImmediate = NT_NOTIFY_IMMEDIATE,
/** Changed locally.
/**
* Changed locally.
* Set this flag to receive notification of both local changes and changes
* coming from remote nodes. By default, notifications are only generated
* for remote changes. Must be combined with some combination of kNew,
@@ -43,23 +48,27 @@ enum {
*/
kLocal = NT_NOTIFY_LOCAL,
/** Newly created entry.
/**
* Newly created entry.
* Set this flag to receive a notification when an entry is created.
*/
kNew = NT_NOTIFY_NEW,
/** Entry was deleted.
/**
* Entry was deleted.
* Set this flag to receive a notification when an entry is deleted.
*/
kDelete = NT_NOTIFY_DELETE,
/** Entry's value changed.
/**
* Entry's value changed.
* Set this flag to receive a notification when an entry's value (or type)
* changes.
*/
kUpdate = NT_NOTIFY_UPDATE,
/** Entry's flags changed.
/**
* Entry's flags changed.
* Set this flag to receive a notification when an entry's flags value
* changes.
*/

48
ntcore/src/main/native/include/networktables/NetworkTable.h
View File

@@ -38,8 +38,15 @@ class NetworkTableInstance;
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
#endif
/**
* @defgroup ntcore_cpp_api ntcore C++ object-oriented API
*
* Recommended interface for C++, identical to Java API.
*/
/**
* A network table that knows its subtable path.
* @ingroup ntcore_cpp_api
*/
class NetworkTable final : public ITable {
private:
@@ -64,6 +71,7 @@ class NetworkTable final : public ITable {
/**
* Gets the "base name" of a key. For example, "/foo/bar" becomes "bar".
* If the key has a trailing slash, returns an empty string.
*
* @param key key
* @return base name
*/
@@ -96,6 +104,7 @@ class NetworkTable final : public ITable {
* Gets a list of the names of all the super tables of a given key. For
* example, the key "/foo/bar/baz" has a hierarchy of "/", "/foo",
* "/foo/bar", and "/foo/bar/baz".
*
* @param key the key
* @return List of super tables
*/
@@ -110,6 +119,7 @@ class NetworkTable final : public ITable {
/**
* Gets the instance for the table.
*
* @return Instance
*/
NetworkTableInstance GetInstance() const;
@@ -153,6 +163,7 @@ class NetworkTable final : public ITable {
* set the team the robot is configured for (this will set the mdns address
* that network tables will connect to in client mode)
* This must be called before initialize or GetTable
*
* @param team the team number
*/
WPI_DEPRECATED(
@@ -181,6 +192,7 @@ class NetworkTable final : public ITable {
/**
* Set the port number that network tables will connect to in client
* mode or listen to in server mode.
*
* @param port the port number
*/
WPI_DEPRECATED(
@@ -192,6 +204,7 @@ class NetworkTable final : public ITable {
/**
* Enable requesting the server address from the Driver Station.
*
* @param enabled whether to enable the connection to the local DS
*/
WPI_DEPRECATED(
@@ -201,6 +214,7 @@ class NetworkTable final : public ITable {
/**
* Sets the persistent filename.
*
* @param filename the filename that the network tables server uses for
* automatic loading and saving of persistent values
*/
@@ -212,6 +226,7 @@ class NetworkTable final : public ITable {
/**
* Sets the network identity.
* This is provided in the connection info on the remote end.
*
* @param name identity
*/
WPI_DEPRECATED("use NetworkTableInstance::SetNetworkIdentity() instead")
@@ -278,6 +293,7 @@ class NetworkTable final : public ITable {
/**
* Gets the entry for a subkey.
*
* @param key the key name
* @return Network table entry.
*/
@@ -285,6 +301,7 @@ class NetworkTable final : public ITable {
/**
* Listen to keys only within this table.
*
* @param listener listener to add
* @param flags EntryListenerFlags bitmask
* @return Listener handle
@@ -294,6 +311,7 @@ class NetworkTable final : public ITable {
/**
* Listen to a single key.
*
* @param key the key name
* @param listener listener to add
* @param flags EntryListenerFlags bitmask
@@ -305,6 +323,7 @@ class NetworkTable final : public ITable {
/**
* Remove an entry listener.
*
* @param listener listener handle
*/
void RemoveEntryListener(NT_EntryListener listener) const;
@@ -313,6 +332,7 @@ class NetworkTable final : public ITable {
* Listen for sub-table creation.
* This calls the listener once for each newly created sub-table.
* It immediately calls the listener for any existing sub-tables.
*
* @param listener listener to add
* @param localNotify notify local changes as well as remote
* @return Listener handle
@@ -322,6 +342,7 @@ class NetworkTable final : public ITable {
/**
* Remove a sub-table listener.
*
* @param listener listener handle
*/
void RemoveTableListener(NT_EntryListener listener) const;
@@ -387,6 +408,7 @@ class NetworkTable final : public ITable {
/**
* Gets all keys in the table (not including sub-tables).
*
* @param types bitmask of types; 0 is treated as a "don't care".
* @return keys currently in the table
*/
@@ -394,6 +416,7 @@ class NetworkTable final : public ITable {
/**
* Gets the names of all subtables in the table.
*
* @return subtables currently in the table
*/
std::vector<std::string> GetSubTables() const override;
@@ -465,6 +488,7 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
@@ -492,6 +516,7 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
@@ -520,6 +545,7 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
@@ -539,6 +565,7 @@ class NetworkTable final : public ITable {
/**
* Put a boolean array in the table
*
* @param key the key to be assigned to
* @param value the value that will be assigned
* @return False if the table key already exists with a different type
@@ -551,9 +578,10 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
* @return False if the table key exists with a different type
*/
bool SetDefaultBooleanArray(StringRef key,
ArrayRef<int> defaultValue) override;
@@ -561,6 +589,7 @@ class NetworkTable final : public ITable {
/**
* Returns the boolean array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
*
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -578,6 +607,7 @@ class NetworkTable final : public ITable {
/**
* Put a number array in the table
*
* @param key the key to be assigned to
* @param value the value that will be assigned
* @return False if the table key already exists with a different type
@@ -586,6 +616,7 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
@@ -596,6 +627,7 @@ class NetworkTable final : public ITable {
/**
* Returns the number array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
*
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -609,6 +641,7 @@ class NetworkTable final : public ITable {
/**
* Put a string array in the table
*
* @param key the key to be assigned to
* @param value the value that will be assigned
* @return False if the table key already exists with a different type
@@ -617,6 +650,7 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
@@ -627,6 +661,7 @@ class NetworkTable final : public ITable {
/**
* Returns the string array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
*
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -640,6 +675,7 @@ class NetworkTable final : public ITable {
/**
* Put a raw value (byte array) in the table
*
* @param key the key to be assigned to
* @param value the value that will be assigned
* @return False if the table key already exists with a different type
@@ -648,15 +684,17 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
* @return False if the table key exists with a different type
*/
bool SetDefaultRaw(StringRef key, StringRef defaultValue) override;
/**
* Returns the raw value (byte array) the key maps to. If the key does not
* exist or is of different type, it will return the default value.
*
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -678,9 +716,10 @@ class NetworkTable final : public ITable {
/**
* Gets the current value in the table, setting it if it does not exist.
*
* @param key the key
* @param defaultValue the default value to set if key doesn't exist.
* @returns False if the table key exists with a different type
* @return False if the table key exists with a different type
*/
bool SetDefaultValue(const Twine& key,
std::shared_ptr<Value> defaultValue) override;
@@ -696,6 +735,7 @@ class NetworkTable final : public ITable {
/**
* Gets the full path of this table. Does not include the trailing "/".
*
* @return The path (e.g "", "/foo").
*/
StringRef GetPath() const override;
@@ -703,6 +743,7 @@ class NetworkTable final : public ITable {
/**
* Save table values to a file. The file format used is identical to
* that used for SavePersistent.
*
* @param filename filename
* @return error string, or nullptr if successful
*/
@@ -711,6 +752,7 @@ class NetworkTable final : public ITable {
/**
* Load table values from a file. The file format used is identical to
* that used for SavePersistent / LoadPersistent.
*
* @param filename filename
* @param warn callback function for warnings
* @return error string, or nullptr if successful

50
ntcore/src/main/native/include/networktables/NetworkTableEntry.h
View File

@@ -31,11 +31,14 @@ using wpi::Twine;
class NetworkTableInstance;
/** NetworkTables Entry */
/**
* NetworkTables Entry
* @ingroup ntcore_cpp_api
*/
class NetworkTableEntry final {
public:
/**
* Flag values (as returned by {@link #getFlags()}).
* Flag values (as returned by GetFlags()).
*/
enum Flags { kPersistent = NT_PERSISTENT };
@@ -46,60 +49,70 @@ class NetworkTableEntry final {
/**
* Construct from native handle.
*
* @param handle Native handle
*/
explicit NetworkTableEntry(NT_Entry handle);
/**
* 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; }
/**
* Gets the native handle for the entry.
*
* @return Native handle
*/
NT_Entry GetHandle() const;
/**
* Gets the instance for the entry.
*
* @return Instance
*/
NetworkTableInstance GetInstance() const;
/**
* Determines if the entry currently exists.
*
* @return True if the entry exists, false otherwise.
*/
bool Exists() const;
/**
* Gets the name of the entry (the key).
*
* @return the entry's name
*/
std::string GetName() const;
/**
* Gets the type of the entry.
*
* @return the entry's type
*/
NetworkTableType GetType() const;
/**
* Returns the flags.
*
* @return the flags (bitmask)
*/
unsigned int GetFlags() const;
/**
* Gets the last time the entry's value was changed.
*
* @return Entry last change time
*/
uint64_t GetLastChange() const;
/**
* Gets combined information about the entry.
*
* @return Entry information
*/
EntryInfo GetInfo() const;
@@ -150,6 +163,7 @@ class NetworkTableEntry final {
/**
* Gets the entry's value as a boolean array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*
@@ -165,6 +179,7 @@ class NetworkTableEntry final {
/**
* Gets the entry's value as a double array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*
@@ -176,6 +191,7 @@ class NetworkTableEntry final {
/**
* Gets the entry's value as a string array. If the entry does not exist
* or is of different type, it will return the default value.
*
* @param defaultValue the value to be returned if no value is found
* @return the entry's value or the given default value
*
@@ -187,6 +203,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -194,6 +211,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -201,6 +219,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -208,6 +227,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -215,6 +235,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -222,6 +243,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -229,6 +251,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -236,6 +259,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value if it does not exist.
*
* @param defaultValue the default value to set
* @return False if the entry exists with a different type
*/
@@ -243,6 +267,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -250,6 +275,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -257,6 +283,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -264,6 +291,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -271,6 +299,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -278,6 +307,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -285,6 +315,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -292,6 +323,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value.
*
* @param value the value to set
* @return False if the entry exists with a different type
*/
@@ -300,6 +332,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetValue(std::shared_ptr<Value> value);
@@ -307,6 +340,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetBoolean(bool value);
@@ -314,6 +348,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetDouble(double value);
@@ -321,6 +356,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetString(const Twine& value);
@@ -328,6 +364,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetRaw(StringRef value);
@@ -335,6 +372,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetBooleanArray(ArrayRef<int> value);
@@ -342,6 +380,7 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetDoubleArray(ArrayRef<double> value);
@@ -349,18 +388,21 @@ class NetworkTableEntry final {
/**
* Sets the entry's value. If the value is of different type, the type is
* changed to match the new value.
*
* @param value the value to set
*/
void ForceSetStringArray(ArrayRef<std::string> value);
/**
* Sets flags.
*
* @param flags the flags to set (bitmask)
*/
void SetFlags(unsigned int flags);
/**
* Clears flags.
*
* @param flags the flags to clear (bitmask)
*/
void ClearFlags(unsigned int flags);
@@ -377,6 +419,7 @@ class NetworkTableEntry final {
/**
* Returns whether the value is persistent through program restarts.
*
* @return True if the value is persistent.
*/
bool IsPersistent() const;
@@ -390,6 +433,7 @@ class NetworkTableEntry final {
* Create a callback-based RPC entry point. Only valid to use on the server.
* The callback function will be called when the RPC is called.
* This function creates RPC version 0 definitions (raw data in and out).
*
* @param callback callback function
*/
void CreateRpc(std::function<void(const RpcAnswer& answer)> callback);
@@ -407,6 +451,7 @@ class NetworkTableEntry final {
* This function is non-blocking. Either RpcCall::GetResult() or
* RpcCall::CancelResult() must be called on the return value to either
* get or ignore the result of the call.
*
* @param params parameter
* @return RPC call object.
*/
@@ -425,6 +470,7 @@ class NetworkTableEntry final {
/**
* Remove an entry listener.
*
* @param entry_listener Listener handle to remove
*/
void RemoveListener(NT_EntryListener entry_listener);

53
ntcore/src/main/native/include/networktables/NetworkTableInstance.h
View File

@@ -29,7 +29,8 @@ using wpi::ArrayRef;
using wpi::StringRef;
using wpi::Twine;
/** NetworkTables Instance.
/**
* 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
@@ -46,6 +47,8 @@ using wpi::Twine;
* Additional instances can be created with the Create() function.
* Instances are not reference counted or RAII. Instead, they must be
* explicitly destroyed (with Destroy()).
*
* @ingroup ntcore_cpp_api
*/
class NetworkTableInstance final {
public:
@@ -88,42 +91,49 @@ class NetworkTableInstance final {
/**
* Construct from native handle.
*
* @param handle Native handle
*/
explicit NetworkTableInstance(NT_Inst inst) 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.
*/
@@ -131,6 +141,7 @@ class NetworkTableInstance final {
/**
* 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.
*
@@ -144,6 +155,7 @@ class NetworkTableInstance final {
/**
* 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.
*
@@ -170,8 +182,8 @@ class NetworkTableInstance final {
void DeleteAllEntries();
/**
* @defgroup EntryListenerFunctions Entry Listener Functions
* @{
* @name Entry Listener Functions
*/
/**
@@ -189,6 +201,7 @@ class NetworkTableInstance final {
/**
* Remove an entry listener.
*
* @param entry_listener Listener handle to remove
*/
static void RemoveEntryListener(NT_EntryListener entry_listener);
@@ -198,6 +211,7 @@ class NetworkTableInstance final {
* 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.
@@ -207,8 +221,8 @@ class NetworkTableInstance final {
/** @} */
/**
* @defgroup ConnectionListenerFunctions Connection Listener Functions
* @{
* @name Connection Listener Functions
*/
/**
@@ -224,17 +238,17 @@ class NetworkTableInstance final {
/**
* 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.
* 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.
@@ -244,8 +258,8 @@ class NetworkTableInstance final {
/** @} */
/**
* @defgroup RpcFunctions Remote Procedure Call Functions
* @{
* @name Remote Procedure Call Functions
*/
/**
@@ -253,6 +267,7 @@ class NetworkTableInstance final {
* 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.
@@ -262,20 +277,23 @@ class NetworkTableInstance final {
/** @} */
/**
* @defgroup NetworkFunctions Client/Server Functions
* @{
* @name 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;
@@ -410,12 +428,14 @@ class NetworkTableInstance final {
/**
* 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;
@@ -423,14 +443,15 @@ class NetworkTableInstance final {
/** @} */
/**
* @defgroup FileFunctions File Save/Load Functions
* @{
* @name 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
*/
@@ -440,6 +461,7 @@ class NetworkTableInstance final {
* 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
@@ -451,6 +473,7 @@ class NetworkTableInstance final {
/**
* 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
@@ -460,6 +483,7 @@ class NetworkTableInstance final {
/**
* 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
@@ -472,8 +496,8 @@ class NetworkTableInstance final {
/** @} */
/**
* @defgroup LoggerFunctions Logger Functions
* @{
* @name Logger Functions
*/
/**
@@ -493,16 +517,17 @@ class NetworkTableInstance final {
/**
* 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
* 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.

4
ntcore/src/main/native/include/networktables/NetworkTableType.h
View File

@@ -12,6 +12,10 @@
namespace nt {
/**
* NetworkTable entry type.
* @ingroup ntcore_cpp_api
*/
enum class NetworkTableType {
kUnassigned = NT_UNASSIGNED,
kBoolean = NT_BOOLEAN,

55
ntcore/src/main/native/include/networktables/NetworkTableValue.h
View File

@@ -31,6 +31,7 @@ using wpi::Twine;
/**
* A network table entry value.
* @ingroup ntcore_cpp_api
*/
class Value final {
struct private_init {};
@@ -42,83 +43,96 @@ class Value final {
/**
* Get the data type.
*
* @return The type.
*/
NT_Type type() const { return m_val.type; }
/**
* Get the data value stored.
*
* @return The type.
*/
const NT_Value& value() const { return m_val; }
/**
* Get the creation time of the value.
*
* @return The time, in the units returned by nt::Now().
*/
uint64_t last_change() const { return m_val.last_change; }
/**
* Get the creation time of the value.
*
* @return The time, in the units returned by nt::Now().
*/
uint64_t time() const { return m_val.last_change; }
/**
* @defgroup TypeCheckers Type Checkers
* @{
* @name Type Checkers
*/
/**
* Determine if entry value contains a value or is unassigned.
*
* @return True if the entry value contains a value.
*/
bool IsValid() const { return m_val.type != NT_UNASSIGNED; }
/**
* Determine if entry value contains a boolean.
*
* @return True if the entry value is of boolean type.
*/
bool IsBoolean() const { return m_val.type == NT_BOOLEAN; }
/**
* Determine if entry value contains a double.
*
* @return True if the entry value is of double type.
*/
bool IsDouble() const { return m_val.type == NT_DOUBLE; }
/**
* Determine if entry value contains a string.
*
* @return True if the entry value is of string type.
*/
bool IsString() const { return m_val.type == NT_STRING; }
/**
* Determine if entry value contains a raw.
*
* @return True if the entry value is of raw type.
*/
bool IsRaw() const { return m_val.type == NT_RAW; }
/**
* Determine if entry value contains a rpc definition.
*
* @return True if the entry value is of rpc definition type.
*/
bool IsRpc() const { return m_val.type == NT_RPC; }
/**
* Determine if entry value contains a boolean array.
*
* @return True if the entry value is of boolean array type.
*/
bool IsBooleanArray() const { return m_val.type == NT_BOOLEAN_ARRAY; }
/**
* Determine if entry value contains a double array.
*
* @return True if the entry value is of double array type.
*/
bool IsDoubleArray() const { return m_val.type == NT_DOUBLE_ARRAY; }
/**
* Determine if entry value contains a string array.
*
* @return True if the entry value is of string array type.
*/
bool IsStringArray() const { return m_val.type == NT_STRING_ARRAY; }
@@ -126,12 +140,13 @@ class Value final {
/** @} */
/**
* @defgroup TypeSafeGetters Type-Safe Getters
* @{
* @name Type-Safe Getters
*/
/**
* Get the entry's boolean value.
*
* @return The boolean value.
*/
bool GetBoolean() const {
@@ -141,6 +156,7 @@ class Value final {
/**
* Get the entry's double value.
*
* @return The double value.
*/
double GetDouble() const {
@@ -150,6 +166,7 @@ class Value final {
/**
* Get the entry's string value.
*
* @return The string value.
*/
StringRef GetString() const {
@@ -159,6 +176,7 @@ class Value final {
/**
* Get the entry's raw value.
*
* @return The raw value.
*/
StringRef GetRaw() const {
@@ -168,6 +186,7 @@ class Value final {
/**
* Get the entry's rpc definition value.
*
* @return The rpc definition value.
*/
StringRef GetRpc() const {
@@ -177,6 +196,7 @@ class Value final {
/**
* Get the entry's boolean array value.
*
* @return The boolean array value.
*/
ArrayRef<int> GetBooleanArray() const {
@@ -187,6 +207,7 @@ class Value final {
/**
* Get the entry's double array value.
*
* @return The double array value.
*/
ArrayRef<double> GetDoubleArray() const {
@@ -197,6 +218,7 @@ class Value final {
/**
* Get the entry's string array value.
*
* @return The string array value.
*/
ArrayRef<std::string> GetStringArray() const {
@@ -207,12 +229,13 @@ class Value final {
/** @} */
/**
* @defgroup Factories Factory functions
* @{
* @name Factory functions
*/
/**
* Creates a boolean entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -226,6 +249,7 @@ class Value final {
/**
* Creates a double entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -239,6 +263,7 @@ class Value final {
/**
* Creates a string entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -255,6 +280,7 @@ class Value final {
/**
* Creates a string entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -277,6 +303,7 @@ class Value final {
/**
* Creates a raw entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -292,6 +319,7 @@ class Value final {
/**
* Creates a raw entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -314,6 +342,7 @@ class Value final {
/**
* Creates a rpc entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -329,6 +358,7 @@ class Value final {
/**
* Creates a rpc entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -345,6 +375,7 @@ class Value final {
/**
* Creates a boolean array entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -355,6 +386,7 @@ class Value final {
/**
* Creates a double array entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -365,6 +397,7 @@ class Value final {
/**
* Creates a string array entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
@@ -373,7 +406,16 @@ class Value final {
static std::shared_ptr<Value> MakeStringArray(ArrayRef<std::string> value,
uint64_t time = 0);
// Note: This function moves the values out of the vector.
/**
* Creates a string array entry value.
*
* @param value the value
* @param time if nonzero, the creation time to use (instead of the current
* time)
* @return The entry value
*
* @note This function moves the values out of the vector.
*/
static std::shared_ptr<Value> MakeStringArray(
std::vector<std::string>&& value, uint64_t time = 0);
@@ -394,7 +436,10 @@ inline bool operator!=(const Value& lhs, const Value& rhs) {
return !(lhs == rhs);
}
/** NetworkTable Value alias for similarity with Java. */
/**
* NetworkTable Value alias for similarity with Java.
* @ingroup ntcore_cpp_api
*/
typedef Value NetworkTableValue;
} // namespace nt

11
ntcore/src/main/native/include/networktables/RpcCall.h
View File

@@ -17,7 +17,10 @@ namespace nt {
class NetworkTableEntry;
/** NetworkTables Remote Procedure Call */
/**
* NetworkTables Remote Procedure Call
* @ingroup ntcore_cpp_api
*/
class RpcCall final {
public:
/**
@@ -27,6 +30,7 @@ class RpcCall final {
/**
* Construct from native handles.
*
* @param entry Entry handle
* @param call Call handle
*/
@@ -43,18 +47,21 @@ class RpcCall final {
/**
* Determines if the native handle is valid.
*
* @return True if the native handle is valid, false otherwise.
*/
explicit operator bool() const { return m_call != 0; }
/**
* Get the RPC entry.
*
* @return NetworkTableEntry for the RPC.
*/
NetworkTableEntry GetEntry() const;
/**
* Get the call native handle.
*
* @return Native handle.
*/
NT_RpcCall GetCall() const { return m_call; }
@@ -62,6 +69,7 @@ class RpcCall final {
/**
* Get the result (return value). This function blocks until
* the result is received.
*
* @param result received result (output)
* @return False on error, true otherwise.
*/
@@ -70,6 +78,7 @@ class RpcCall final {
/**
* Get the result (return value). This function blocks until
* the result is received or it times out.
*
* @param result received result (output)
* @param timeout timeout, in seconds
* @param timed_out true if the timeout period elapsed (output)

2
ntcore/src/main/native/include/networktables/TableEntryListener.h
View File

@@ -32,6 +32,8 @@ using wpi::StringRef;
* @param value the new value
* @param flags update flags; for example, EntryListenerFlags.kNew if the key
* did not previously exist
*
* @ingroup ntcore_cpp_api
*/
typedef std::function<void(NetworkTable* table, StringRef name,
NetworkTableEntry entry,

2
ntcore/src/main/native/include/networktables/TableListener.h
View File

@@ -27,6 +27,8 @@ using wpi::StringRef;
* @param parent the parent of the table
* @param name the name of the new table
* @param table the new table
*
* @ingroup ntcore_cpp_api
*/
typedef std::function<void(NetworkTable* parent, StringRef name,
NetworkTable* table)>

137
ntcore/src/main/native/include/ntcore_c.h
View File

@@ -22,6 +22,14 @@
extern "C" {
#endif
/**
* @defgroup ntcore_c_api ntcore C API
*
* Handle-based interface for C.
*
* @{
*/
/** Typedefs */
typedef int NT_Bool;
@@ -262,19 +270,21 @@ struct NT_LogMessage {
};
/**
* @defgroup InstanceFunctions Instance Functions
* @defgroup ntcore_instance_cfunc Instance Functions
* @{
*/
/**
* Get default instance.
* This is the instance used by non-handle-taking functions.
*
* @return Instance handle
*/
NT_Inst NT_GetDefaultInstance(void);
/**
* Create an instance.
*
* @return Instance handle
*/
NT_Inst NT_CreateInstance(void);
@@ -282,12 +292,14 @@ NT_Inst NT_CreateInstance(void);
/**
* Destroy an instance.
* The default instance cannot be destroyed.
*
* @param inst Instance handle
*/
void NT_DestroyInstance(NT_Inst inst);
/**
* Get instance handle from another handle.
*
* @param handle handle
* @return Instance handle
*/
@@ -296,12 +308,13 @@ NT_Inst NT_GetInstanceFromHandle(NT_Handle handle);
/** @} */
/**
* @defgroup TableFunctions Table Functions
* @defgroup ntcore_table_cfunc Table Functions
* @{
*/
/**
* Get Entry Handle.
*
* @param inst instance handle
* @param name entry name (UTF-8 string)
* @param name_len length of name in bytes
@@ -311,6 +324,7 @@ NT_Entry NT_GetEntry(NT_Inst inst, const char* name, size_t name_len);
/**
* Get Entry Handles.
*
* Returns an array of entry handles. The results are optionally
* filtered by string prefix and entry type to only return a subset of all
* entries.
@@ -328,6 +342,7 @@ NT_Entry* NT_GetEntries(NT_Inst inst, const char* prefix, size_t prefix_len,
/**
* Gets the name of the specified entry.
* Returns an empty string if the handle is invalid.
*
* @param entry entry handle
* @param name_len length of the returned string (output parameter)
* @return Entry name
@@ -336,6 +351,7 @@ char* NT_GetEntryName(NT_Entry entry, size_t* name_len);
/**
* Gets the type for the specified key, or unassigned if non existent.
*
* @param entry entry handle
* @return Entry type
*/
@@ -344,6 +360,7 @@ enum NT_Type NT_GetEntryType(NT_Entry entry);
/**
* Gets the last time the entry was changed.
* Returns 0 if the handle is invalid.
*
* @param entry entry handle
* @return Entry last change time
*/
@@ -351,6 +368,7 @@ uint64_t NT_GetEntryLastChange(NT_Entry entry);
/**
* Get Entry Value.
*
* Returns copy of current entry value.
* Note that one of the type options is "unassigned".
*
@@ -365,6 +383,7 @@ void NT_GetEntryValue(NT_Entry entry, struct NT_Value* value);
/**
* Set Default Entry Value.
*
* Returns copy of current entry value if it exists.
* Otherwise, sets passed in value, and returns set value.
* Note that one of the type options is "unassigned".
@@ -378,6 +397,7 @@ NT_Bool NT_SetDefaultEntryValue(NT_Entry entry,
/**
* Set Entry Value.
*
* Sets new entry value. If type of new value differs from the type of the
* currently stored entry, returns error and does not update value.
*
@@ -389,6 +409,7 @@ NT_Bool NT_SetEntryValue(NT_Entry entry, const struct NT_Value* value);
/**
* Set Entry Type and Value.
*
* Sets new entry value. If type of new value differs from the type of the
* currently stored entry, the currently stored entry type is overridden
* (generally this will generate an Entry Assignment message).
@@ -403,6 +424,7 @@ void NT_SetEntryTypeValue(NT_Entry entry, const struct NT_Value* value);
/**
* Set Entry Flags.
*
* @param entry entry handle
* @param flags flags value (bitmask of NT_EntryFlags)
*/
@@ -410,6 +432,7 @@ void NT_SetEntryFlags(NT_Entry entry, unsigned int flags);
/**
* Get Entry Flags.
*
* @param entry entry handle
* @return Flags value (bitmask of NT_EntryFlags)
*/
@@ -417,6 +440,7 @@ unsigned int NT_GetEntryFlags(NT_Entry entry);
/**
* Delete Entry.
*
* Deletes an entry. This is a new feature in version 3.0 of the protocol,
* so this may not have an effect if any other node in the network is not
* version 3.0 or newer.
@@ -431,6 +455,7 @@ void NT_DeleteEntry(NT_Entry entry);
/**
* Delete All Entries.
*
* Deletes ALL table entries. This is a new feature in version 3.0 of the
* so this may not have an effect if any other node in the network is not
* version 3.0 or newer.
@@ -445,6 +470,7 @@ void NT_DeleteAllEntries(NT_Inst inst);
/**
* Get Entry Information.
*
* Returns an array of entry information (entry handle, name, entry type,
* and timestamp of last change to type/value). The results are optionally
* filtered by string prefix and entry type to only return a subset of all
@@ -465,6 +491,7 @@ struct NT_EntryInfo* NT_GetEntryInfo(NT_Inst inst, const char* prefix,
/**
* Get Entry Information.
*
* Returns information about an entry (name, entry type,
* and timestamp of last change to type/value).
*
@@ -477,7 +504,7 @@ NT_Bool NT_GetEntryInfoHandle(NT_Entry entry, struct NT_EntryInfo* info);
/** @} */
/**
* @defgroup EntryListenerFunctions Entry Listener Functions
* @defgroup ntcore_entrylistener_cfunc Entry Listener Functions
* @{
*/
@@ -522,10 +549,12 @@ NT_EntryListener NT_AddEntryListenerSingle(NT_Entry entry, void* data,
/**
* Create a entry listener poller.
*
* A poller provides a single queue of poll events. Events linked to this
* poller (using NT_AddPolledEntryListener()) will be stored in the queue and
* must be collected by calling NT_PollEntryListener().
* The returned handle must be destroyed with NT_DestroyEntryListenerPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -534,6 +563,7 @@ NT_EntryListenerPoller NT_CreateEntryListenerPoller(NT_Inst inst);
/**
* Destroy a entry listener poller. This will abort any blocked polling
* call and prevent additional events from being generated for this poller.
*
* @param poller poller handle
*/
void NT_DestroyEntryListenerPoller(NT_EntryListenerPoller poller);
@@ -541,6 +571,7 @@ void NT_DestroyEntryListenerPoller(NT_EntryListenerPoller poller);
/**
* Create a polled entry listener.
* The caller is responsible for calling NT_PollEntryListener() to poll.
*
* @param poller poller handle
* @param prefix UTF-8 string prefix
* @param flags NT_NotifyKind bitmask
@@ -554,6 +585,7 @@ NT_EntryListener NT_AddPolledEntryListener(NT_EntryListenerPoller poller,
/**
* Create a polled entry listener.
* The caller is responsible for calling NT_PollEntryListener() to poll.
*
* @param poller poller handle
* @param prefix UTF-8 string prefix
* @param flags NT_NotifyKind bitmask
@@ -565,9 +597,11 @@ NT_EntryListener NT_AddPolledEntryListenerSingle(NT_EntryListenerPoller poller,
/**
* Get the next entry listener event. This blocks until the next event occurs.
*
* This is intended to be used with NT_AddPolledEntryListener(void); entry
* listeners created using NT_AddEntryListener() will not be serviced through
* this function.
*
* @param poller poller handle
* @param len length of returned array (output)
* @return Array of information on the entry listener events. Returns NULL if
@@ -581,6 +615,7 @@ struct NT_EntryNotification* NT_PollEntryListener(NT_EntryListenerPoller poller,
* or it times out. This is intended to be used with
* NT_AddPolledEntryListener(); entry listeners created using
* NT_AddEntryListener() will not be serviced through this function.
*
* @param poller poller handle
* @param len length of returned array (output)
* @param timeout timeout, in seconds
@@ -597,12 +632,14 @@ struct NT_EntryNotification* NT_PollEntryListenerTimeout(
* Cancel a PollEntryListener call. This wakes up a call to
* PollEntryListener for this poller and causes it to immediately return
* an empty array.
*
* @param poller poller handle
*/
void NT_CancelPollEntryListener(NT_EntryListenerPoller poller);
/**
* Remove an entry listener.
*
* @param entry_listener Listener handle to remove
*/
void NT_RemoveEntryListener(NT_EntryListener entry_listener);
@@ -612,6 +649,7 @@ void NT_RemoveEntryListener(NT_EntryListener entry_listener);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -622,7 +660,7 @@ NT_Bool NT_WaitForEntryListenerQueue(NT_Inst inst, double timeout);
/** @} */
/**
* @defgroup ConnectionListenerFunctions Connection Listener Functions
* @defgroup ntcore_connectionlistener_cfunc Connection Listener Functions
* @{
*/
@@ -656,6 +694,7 @@ NT_ConnectionListener NT_AddConnectionListener(
* and must be collected by calling NT_PollConnectionListener().
* The returned handle must be destroyed with
* NT_DestroyConnectionListenerPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -664,6 +703,7 @@ NT_ConnectionListenerPoller NT_CreateConnectionListenerPoller(NT_Inst inst);
/**
* Destroy a connection listener poller. This will abort any blocked polling
* call and prevent additional events from being generated for this poller.
*
* @param poller poller handle
*/
void NT_DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller);
@@ -671,6 +711,7 @@ void NT_DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller);
/**
* Create a polled connection listener.
* The caller is responsible for calling NT_PollConnectionListener() to poll.
*
* @param poller poller handle
* @param immediate_notify notify listener of all existing connections
*/
@@ -682,6 +723,7 @@ NT_ConnectionListener NT_AddPolledConnectionListener(
* disconnect occurs. This is intended to be used with
* NT_AddPolledConnectionListener(); connection listeners created using
* NT_AddConnectionListener() will not be serviced through this function.
*
* @param poller poller handle
* @param len length of returned array (output)
* @return Array of information on the connection events. Only returns NULL
@@ -696,6 +738,7 @@ struct NT_ConnectionNotification* NT_PollConnectionListener(
* disconnect occurs or it times out. This is intended to be used with
* NT_AddPolledConnectionListener(); connection listeners created using
* NT_AddConnectionListener() will not be serviced through this function.
*
* @param poller poller handle
* @param len length of returned array (output)
* @param timeout timeout, in seconds
@@ -712,12 +755,14 @@ struct NT_ConnectionNotification* NT_PollConnectionListenerTimeout(
* Cancel a PollConnectionListener call. This wakes up a call to
* PollConnectionListener for this poller and causes it to immediately return
* an empty array.
*
* @param poller poller handle
*/
void NT_CancelPollConnectionListener(NT_ConnectionListenerPoller poller);
/**
* Remove a connection listener.
*
* @param conn_listener Listener handle to remove
*/
void NT_RemoveConnectionListener(NT_ConnectionListener conn_listener);
@@ -727,6 +772,7 @@ void NT_RemoveConnectionListener(NT_ConnectionListener conn_listener);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -737,14 +783,16 @@ NT_Bool NT_WaitForConnectionListenerQueue(NT_Inst inst, double timeout);
/** @} */
/**
* @defgroup RpcFunctions Remote Procedure Call Functions
* @defgroup ntcore_rpc_cfunc Remote Procedure Call Functions
* @{
*/
/**
* Remote Procedure Call (RPC) callback function.
*
* @param data data pointer provided to NT_CreateRpc()
* @param call call information
*
* Note: NT_PostRpcResponse() must be called by the callback to provide a
* response to the call.
*/
@@ -753,6 +801,7 @@ typedef void (*NT_RpcCallback)(void* data, const struct NT_RpcAnswer* call);
/**
* Create a callback-based RPC entry point. Only valid to use on the server.
* The callback function will be called when the RPC is called.
*
* @param entry entry handle of RPC entry
* @param def RPC definition
* @param def_len length of def in bytes
@@ -764,10 +813,12 @@ void NT_CreateRpc(NT_Entry entry, const char* def, size_t def_len, void* data,
/**
* Create a RPC call poller. Only valid to use on the server.
*
* A poller provides a single queue of poll events. Events linked to this
* poller (using NT_CreatePolledRpc()) will be stored in the queue and must be
* collected by calling NT_PollRpc() or NT_PollRpcTimeout().
* The returned handle must be destroyed with NT_DestroyRpcCallPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -776,14 +827,17 @@ NT_RpcCallPoller NT_CreateRpcCallPoller(NT_Inst inst);
/**
* Destroy a RPC call poller. This will abort any blocked polling call and
* prevent additional events from being generated for this poller.
*
* @param poller poller handle
*/
void NT_DestroyRpcCallPoller(NT_RpcCallPoller poller);
/**
* Create a polled RPC entry point. Only valid to use on the server.
*
* The caller is responsible for calling NT_PollRpc() or NT_PollRpcTimeout()
* to poll for servicing incoming RPC calls.
*
* @param entry entry handle of RPC entry
* @param def RPC definition
* @param def_len length of def in bytes
@@ -799,6 +853,7 @@ void NT_CreatePolledRpc(NT_Entry entry, const char* def, size_t def_len,
* function. Upon successful return, NT_PostRpcResponse() must be called to
* send the return value to the caller. The returned array must be freed
* using NT_DisposeRpcAnswerArray().
*
* @param poller poller handle
* @param len length of returned array (output)
* @return Array of RPC call information. Only returns NULL if an error
@@ -813,6 +868,7 @@ struct NT_RpcAnswer* NT_PollRpc(NT_RpcCallPoller poller, size_t* len);
* serviced through this function. Upon successful return,
* NT_PostRpcResponse() must be called to send the return value to the caller.
* The returned array must be freed using NT_DisposeRpcAnswerArray().
*
* @param poller poller handle
* @param len length of returned array (output)
* @param timeout timeout, in seconds
@@ -827,6 +883,7 @@ struct NT_RpcAnswer* NT_PollRpcTimeout(NT_RpcCallPoller poller, size_t* len,
/**
* Cancel a PollRpc call. This wakes up a call to PollRpc for this poller
* and causes it to immediately return an empty array.
*
* @param poller poller handle
*/
void NT_CancelPollRpc(NT_RpcCallPoller poller);
@@ -836,6 +893,7 @@ void NT_CancelPollRpc(NT_RpcCallPoller poller);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -845,8 +903,10 @@ NT_Bool NT_WaitForRpcCallQueue(NT_Inst inst, double timeout);
/**
* Post RPC response (return value) for a polled RPC.
*
* The rpc and call parameters should come from the NT_RpcAnswer returned
* by NT_PollRpc().
*
* @param entry entry handle of RPC entry (from NT_RpcAnswer)
* @param call RPC call handle (from NT_RpcAnswer)
* @param result result raw data that will be provided to remote caller
@@ -858,9 +918,11 @@ NT_Bool NT_PostRpcResponse(NT_Entry entry, NT_RpcCall call, const char* result,
/**
* Call a RPC function. May be used on either the client or server.
*
* This function is non-blocking. Either NT_GetRpcResult() or
* NT_CancelRpcResult() must be called to either get or ignore the result of
* the call.
*
* @param entry entry handle of RPC entry
* @param params parameter
* @param params_len length of param in bytes
@@ -872,6 +934,7 @@ NT_RpcCall NT_CallRpc(NT_Entry entry, const char* params, size_t params_len);
/**
* Get the result (return value) of a RPC call. This function blocks until
* the result is received.
*
* @param entry entry handle of RPC entry
* @param call RPC call handle returned by NT_CallRpc()
* @param result_len length of returned result in bytes
@@ -882,6 +945,7 @@ char* NT_GetRpcResult(NT_Entry entry, NT_RpcCall call, size_t* result_len);
/**
* Get the result (return value) of a RPC call. This function blocks until
* the result is received or it times out.
*
* @param entry entry handle of RPC entry
* @param call RPC call handle returned by NT_CallRpc()
* @param result_len length of returned result in bytes
@@ -895,6 +959,7 @@ char* NT_GetRpcResultTimeout(NT_Entry entry, NT_RpcCall call,
/**
* Ignore the result of a RPC call. This function is non-blocking.
*
* @param entry entry handle of RPC entry
* @param call RPC call handle returned by NT_CallRpc()
*/
@@ -902,6 +967,7 @@ void NT_CancelRpcResult(NT_Entry entry, NT_RpcCall call);
/**
* Pack a RPC version 1 definition.
*
* @param def RPC version 1 definition
* @param packed_len length of return value in bytes
* @return Raw packed bytes. Use C standard library std::free() to release.
@@ -912,6 +978,7 @@ char* NT_PackRpcDefinition(const struct NT_RpcDefinition* def,
/**
* Unpack a RPC version 1 definition. This can be used for introspection or
* validation.
*
* @param packed raw packed bytes
* @param packed_len length of packed in bytes
* @param def RPC version 1 definition (output)
@@ -922,6 +989,7 @@ NT_Bool NT_UnpackRpcDefinition(const char* packed, size_t packed_len,
/**
* Pack RPC values as required for RPC version 1 definition messages.
*
* @param values array of values to pack
* @param values_len length of values
* @param packed_len length of return value in bytes
@@ -932,6 +1000,7 @@ char* NT_PackRpcValues(const struct NT_Value** values, size_t values_len,
/**
* Unpack RPC values as required for RPC version 1 definition messages.
*
* @param packed raw packed bytes
* @param packed_len length of packed in bytes
* @param types array of data types (as provided in the RPC definition)
@@ -945,7 +1014,7 @@ struct NT_Value** NT_UnpackRpcValues(const char* packed, size_t packed_len,
/** @} */
/**
* @defgroup NetworkFunctions Client/Server Functions
* @defgroup ntcore_network_cfunc Client/Server Functions
* @{
*/
@@ -953,6 +1022,7 @@ struct NT_Value** NT_UnpackRpcValues(const char* packed, size_t packed_len,
* Set the network identity of this node.
* This is the name used during the initial connection handshake, and is
* visible through NT_ConnectionInfo on the remote node.
*
* @param inst instance handle
* @param name identity to advertise
* @param name_len length of name in bytes
@@ -961,6 +1031,7 @@ void NT_SetNetworkIdentity(NT_Inst inst, const char* name, size_t name_len);
/**
* Get the current network mode.
*
* @param inst instance handle
* @return Bitmask of NT_NetworkMode.
*/
@@ -981,12 +1052,14 @@ void NT_StartServer(NT_Inst inst, const char* persist_filename,
/**
* Stops the server if it is running.
*
* @param inst instance handle
*/
void NT_StopServer(NT_Inst inst);
/**
* Starts a client. Use NT_SetServer to set the server name and port.
*
* @param inst instance handle
*/
void NT_StartClientNone(NT_Inst inst);
@@ -1024,6 +1097,7 @@ void NT_StartClientTeam(NT_Inst inst, unsigned int team, unsigned int port);
/**
* Stops the client if it is running.
*
* @param inst instance handle
*/
void NT_StopClient(NT_Inst inst);
@@ -1072,6 +1146,7 @@ void NT_StartDSClient(NT_Inst inst, unsigned int port);
/**
* Stops requesting server address from Driver Station.
*
* @param inst instance handle
*/
void NT_StopDSClient(NT_Inst inst);
@@ -1087,6 +1162,7 @@ void NT_SetUpdateRate(NT_Inst inst, double interval);
/**
* Flush Entries.
*
* Forces an immediate flush of all local entry changes to network.
* Normally this is done on a regularly scheduled interval (see
* NT_SetUpdateRate()).
@@ -1114,6 +1190,7 @@ struct NT_ConnectionInfo* NT_GetConnections(NT_Inst inst, size_t* count);
/**
* Return whether or not the instance is connected to another node.
*
* @param inst instance handle
* @return True if connected.
*/
@@ -1122,7 +1199,7 @@ NT_Bool NT_IsConnected(NT_Inst inst);
/** @} */
/**
* @defgroup FileFunctions File Save/Load Functions
* @defgroup ntcore_file_cfunc File Save/Load Functions
* @{
*/
@@ -1130,6 +1207,7 @@ NT_Bool NT_IsConnected(NT_Inst inst);
* 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 inst instance handle
* @param filename filename
* @return error string, or NULL if successful
@@ -1140,6 +1218,7 @@ const char* NT_SavePersistent(NT_Inst inst, const char* filename);
* 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 inst instance handle
* @param filename filename
* @param warn callback function for warnings
@@ -1151,6 +1230,7 @@ const char* NT_LoadPersistent(NT_Inst inst, const char* filename,
/**
* Save table values to a file. The file format used is identical to
* that used for SavePersistent.
*
* @param inst instance handle
* @param filename filename
* @param prefix save only keys starting with this prefix
@@ -1163,6 +1243,7 @@ const char* NT_SaveEntries(NT_Inst inst, const char* filename,
/**
* Load table values from a file. The file format used is identical to
* that used for SavePersistent / LoadPersistent.
*
* @param inst instance handle
* @param filename filename
* @param prefix load only keys starting with this prefix
@@ -1177,12 +1258,13 @@ const char* NT_LoadEntries(NT_Inst inst, const char* filename,
/** @} */
/**
* @defgroup UtilityFunctions Utility Functions
* @defgroup ntcore_utility_cfunc Utility Functions
* @{
*/
/**
* Frees value memory.
*
* @param value value to free
*/
void NT_DisposeValue(struct NT_Value* value);
@@ -1190,12 +1272,14 @@ void NT_DisposeValue(struct NT_Value* value);
/**
* Initializes a NT_Value.
* Sets type to NT_UNASSIGNED and clears rest of struct.
*
* @param value value to initialize
*/
void NT_InitValue(struct NT_Value* value);
/**
* Frees string memory.
*
* @param str string to free
*/
void NT_DisposeString(struct NT_String* str);
@@ -1203,12 +1287,14 @@ void NT_DisposeString(struct NT_String* str);
/**
* Initializes a NT_String.
* Sets length to zero and pointer to null.
*
* @param str string to initialize
*/
void NT_InitString(struct NT_String* str);
/**
* Disposes an entry handle array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1216,6 +1302,7 @@ void NT_DisposeEntryArray(NT_Entry* arr, size_t count);
/**
* Disposes a connection info array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1223,6 +1310,7 @@ void NT_DisposeConnectionInfoArray(struct NT_ConnectionInfo* arr, size_t count);
/**
* Disposes an entry info array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1230,18 +1318,21 @@ void NT_DisposeEntryInfoArray(struct NT_EntryInfo* arr, size_t count);
/**
* Disposes a single entry info (as returned by NT_GetEntryInfoHandle).
*
* @param info pointer to the info to dispose
*/
void NT_DisposeEntryInfo(struct NT_EntryInfo* info);
/**
* Disposes a Rpc Definition structure.
*
* @param def pointer to the struct to dispose
*/
void NT_DisposeRpcDefinition(struct NT_RpcDefinition* def);
/**
* Disposes a Rpc Answer array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1249,12 +1340,14 @@ void NT_DisposeRpcAnswerArray(struct NT_RpcAnswer* arr, size_t count);
/**
* Disposes a Rpc Answer structure.
*
* @param answer pointer to the struct to dispose
*/
void NT_DisposeRpcAnswer(struct NT_RpcAnswer* answer);
/**
* Disposes an entry notification array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1263,12 +1356,14 @@ void NT_DisposeEntryNotificationArray(struct NT_EntryNotification* arr,
/**
* Disposes a single entry notification.
*
* @param info pointer to the info to dispose
*/
void NT_DisposeEntryNotification(struct NT_EntryNotification* info);
/**
* Disposes a connection notification array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1277,12 +1372,14 @@ void NT_DisposeConnectionNotificationArray(
/**
* Disposes a single connection notification.
*
* @param info pointer to the info to dispose
*/
void NT_DisposeConnectionNotification(struct NT_ConnectionNotification* info);
/**
* Disposes a log message array.
*
* @param arr pointer to the array to dispose
* @param count number of elements in the array
*/
@@ -1290,6 +1387,7 @@ void NT_DisposeLogMessageArray(struct NT_LogMessage* arr, size_t count);
/**
* Disposes a single log message.
*
* @param info pointer to the info to dispose
*/
void NT_DisposeLogMessage(struct NT_LogMessage* info);
@@ -1298,6 +1396,7 @@ void NT_DisposeLogMessage(struct NT_LogMessage* info);
* Returns monotonic current time in 1 us increments.
* This is the same time base used for entry and connection timestamps.
* This function is a compatibility wrapper around WPI_Now().
*
* @return Timestamp
*/
uint64_t NT_Now(void);
@@ -1305,12 +1404,13 @@ uint64_t NT_Now(void);
/** @} */
/**
* @defgroup LoggerFunctions Logger Functions
* @defgroup ntcore_logger_cfunc Logger Functions
* @{
*/
/**
* Log function.
*
* @param data data pointer passed to NT_AddLogger()
* @param msg message information
*/
@@ -1336,6 +1436,7 @@ NT_Logger NT_AddLogger(NT_Inst inst, void* data, NT_LogFunc func,
/**
* Create a log poller. A poller provides a single queue of poll events.
* The returned handle must be destroyed with NT_DestroyLoggerPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -1344,6 +1445,7 @@ NT_LoggerPoller NT_CreateLoggerPoller(NT_Inst inst);
/**
* Destroy a log poller. This will abort any blocked polling call and prevent
* additional events from being generated for this poller.
*
* @param poller poller handle
*/
void NT_DestroyLoggerPoller(NT_LoggerPoller poller);
@@ -1352,6 +1454,7 @@ void NT_DestroyLoggerPoller(NT_LoggerPoller poller);
* Set the log level for a log poller. Events will only be generated for
* log messages with level greater than or equal to min_level and less than or
* equal to max_level; messages outside this range will be silently ignored.
*
* @param poller poller handle
* @param min_level minimum log level
* @param max_level maximum log level
@@ -1362,6 +1465,7 @@ NT_Logger NT_AddPolledLogger(NT_LoggerPoller poller, unsigned int min_level,
/**
* Get the next log event. This blocks until the next log occurs.
*
* @param poller poller handle
* @param len length of returned array (output)
* @return Array of information on the log events. Only returns NULL if an
@@ -1372,6 +1476,7 @@ struct NT_LogMessage* NT_PollLogger(NT_LoggerPoller poller, size_t* len);
/**
* Get the next log event. This blocks until the next log occurs or it times
* out.
*
* @param poller poller handle
* @param len length of returned array (output)
* @param timeout timeout, in seconds
@@ -1386,12 +1491,14 @@ struct NT_LogMessage* NT_PollLoggerTimeout(NT_LoggerPoller poller, size_t* len,
/**
* Cancel a PollLogger call. This wakes up a call to PollLogger for this
* poller and causes it to immediately return an empty array.
*
* @param poller poller handle
*/
void NT_CancelPollLogger(NT_LoggerPoller poller);
/**
* Remove a logger.
*
* @param logger Logger handle to remove
*/
void NT_RemoveLogger(NT_Logger logger);
@@ -1401,6 +1508,7 @@ void NT_RemoveLogger(NT_Logger logger);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -1411,12 +1519,12 @@ NT_Bool NT_WaitForLoggerQueue(NT_Inst inst, double timeout);
/** @} */
/**
* @defgroup InteropFunctions Interop Utility Functions
* @defgroup ntcore_interop_cfunc Interop Utility Functions
* @{
*/
/**
* @defgroup MemoryAllocators Memory Allocators
* @defgroup ntcore_memoryallocators_cfunc Memory Allocators
* @{
*/
@@ -1508,7 +1616,7 @@ void NT_FreeStringArray(struct NT_String* v_string, size_t arr_size);
/** @} */
/**
* @defgroup TypedGetters Typed Getters
* @defgroup ntcore_typedgetters_cfunc Typed Getters
* @{
*/
@@ -1745,7 +1853,7 @@ struct NT_String* NT_GetEntryStringArray(NT_Entry entry, uint64_t* last_change,
/** @} */
/**
* @defgroup SetDefault Set Default Values
* @defgroup ntcore_setdefault_cfunc Set Default Values
* @{
*/
@@ -1851,7 +1959,7 @@ NT_Bool NT_SetDefaultEntryStringArray(NT_Entry entry, uint64_t time,
/** @} */
/**
* @defgroup ValueSetters Entry Value Setters
* @defgroup ntcore_valuesetters_cfunc Entry Value Setters
* @{
*/
@@ -1954,6 +2062,7 @@ NT_Bool NT_SetEntryStringArray(NT_Entry entry, uint64_t time,
/** @} */
/** @} */
/** @} */
#ifdef __cplusplus
} // extern "C"

123
ntcore/src/main/native/include/ntcore_cpp.h
View File

@@ -27,6 +27,14 @@
namespace nt {
/**
* @defgroup ntcore_cpp_handle_api ntcore C++ API
*
* Handle-based interface for C++.
*
* @{
*/
using wpi::ArrayRef;
using wpi::StringRef;
using wpi::Twine;
@@ -272,19 +280,21 @@ class LogMessage {
};
/**
* @defgroup InstanceFunctions Instance Functions
* @defgroup ntcore_instance_func Instance Functions
* @{
*/
/**
* Get default instance.
* This is the instance used by non-handle-taking functions.
*
* @return Instance handle
*/
NT_Inst GetDefaultInstance();
/**
* Create an instance.
*
* @return Instance handle
*/
NT_Inst CreateInstance();
@@ -292,12 +302,14 @@ NT_Inst CreateInstance();
/**
* Destroy an instance.
* The default instance cannot be destroyed.
*
* @param inst Instance handle
*/
void DestroyInstance(NT_Inst inst);
/**
* Get instance handle from another handle.
*
* @param handle entry/instance/etc. handle
* @return Instance handle
*/
@@ -306,12 +318,13 @@ NT_Inst GetInstanceFromHandle(NT_Handle handle);
/** @} */
/**
* @defgroup TableFunctions Table Functions
* @defgroup ntcore_table_func Table Functions
* @{
*/
/**
* Get Entry Handle.
*
* @param inst instance handle
* @param name entry name (UTF-8 string)
* @return entry handle
@@ -320,6 +333,7 @@ NT_Entry GetEntry(NT_Inst inst, const Twine& name);
/**
* Get Entry Handles.
*
* Returns an array of entry handles. The results are optionally
* filtered by string prefix and entry type to only return a subset of all
* entries.
@@ -337,6 +351,7 @@ std::vector<NT_Entry> GetEntries(NT_Inst inst, const Twine& prefix,
/**
* Gets the name of the specified entry.
* Returns an empty string if the handle is invalid.
*
* @param entry entry handle
* @return Entry name
*/
@@ -344,6 +359,7 @@ std::string GetEntryName(NT_Entry entry);
/**
* Gets the type for the specified entry, or unassigned if non existent.
*
* @param entry entry handle
* @return Entry type
*/
@@ -352,6 +368,7 @@ NT_Type GetEntryType(NT_Entry entry);
/**
* Gets the last time the entry was changed.
* Returns 0 if the handle is invalid.
*
* @param entry entry handle
* @return Entry last change time
*/
@@ -359,6 +376,7 @@ uint64_t GetEntryLastChange(NT_Entry entry);
/**
* Get Entry Value.
*
* Returns copy of current entry value.
* Note that one of the type options is "unassigned".
*
@@ -370,6 +388,7 @@ std::shared_ptr<Value> GetEntryValue(StringRef name);
/**
* Get Entry Value.
*
* Returns copy of current entry value.
* Note that one of the type options is "unassigned".
*
@@ -380,6 +399,7 @@ std::shared_ptr<Value> GetEntryValue(NT_Entry entry);
/**
* Set Default Entry Value
*
* Returns copy of current entry value if it exists.
* Otherwise, sets passed in value, and returns set value.
* Note that one of the type options is "unassigned".
@@ -393,6 +413,7 @@ bool SetDefaultEntryValue(StringRef name, std::shared_ptr<Value> value);
/**
* Set Default Entry Value
*
* Returns copy of current entry value if it exists.
* Otherwise, sets passed in value, and returns set value.
* Note that one of the type options is "unassigned".
@@ -405,6 +426,7 @@ bool SetDefaultEntryValue(NT_Entry entry, std::shared_ptr<Value> value);
/**
* Set Entry Value.
*
* Sets new entry value. If type of new value differs from the type of the
* currently stored entry, returns error and does not update value.
*
@@ -417,6 +439,7 @@ bool SetEntryValue(StringRef name, std::shared_ptr<Value> value);
/**
* Set Entry Value.
*
* Sets new entry value. If type of new value differs from the type of the
* currently stored entry, returns error and does not update value.
*
@@ -428,6 +451,7 @@ bool SetEntryValue(NT_Entry entry, std::shared_ptr<Value> value);
/**
* Set Entry Type and Value.
*
* Sets new entry value. If type of new value differs from the type of the
* currently stored entry, the currently stored entry type is overridden
* (generally this will generate an Entry Assignment message).
@@ -443,6 +467,7 @@ void SetEntryTypeValue(StringRef name, std::shared_ptr<Value> value);
/**
* Set Entry Type and Value.
*
* Sets new entry value. If type of new value differs from the type of the
* currently stored entry, the currently stored entry type is overridden
* (generally this will generate an Entry Assignment message).
@@ -457,6 +482,7 @@ void SetEntryTypeValue(NT_Entry entry, std::shared_ptr<Value> value);
/**
* Set Entry Flags.
*
* @param name entry name (UTF-8 string)
* @param flags flags value (bitmask of NT_EntryFlags)
*/
@@ -465,6 +491,7 @@ void SetEntryFlags(StringRef name, unsigned int flags);
/**
* Set Entry Flags.
*
* @param entry entry handle
* @param flags flags value (bitmask of NT_EntryFlags)
*/
@@ -472,6 +499,7 @@ void SetEntryFlags(NT_Entry entry, unsigned int flags);
/**
* Get Entry Flags.
*
* @param name entry name (UTF-8 string)
* @return Flags value (bitmask of NT_EntryFlags)
*/
@@ -480,6 +508,7 @@ unsigned int GetEntryFlags(StringRef name);
/**
* Get Entry Flags.
*
* @param entry entry handle
* @return Flags value (bitmask of NT_EntryFlags)
*/
@@ -487,6 +516,7 @@ unsigned int GetEntryFlags(NT_Entry entry);
/**
* Delete Entry.
*
* Deletes an entry. This is a new feature in version 3.0 of the protocol,
* so this may not have an effect if any other node in the network is not
* version 3.0 or newer.
@@ -502,6 +532,7 @@ void DeleteEntry(StringRef name);
/**
* Delete Entry.
*
* Deletes an entry. This is a new feature in version 3.0 of the protocol,
* so this may not have an effect if any other node in the network is not
* version 3.0 or newer.
@@ -516,6 +547,7 @@ void DeleteEntry(NT_Entry entry);
/**
* Delete All Entries.
*
* Deletes ALL table entries. This is a new feature in version 3.0 of the
* so this may not have an effect if any other node in the network is not
* version 3.0 or newer.
@@ -536,6 +568,7 @@ void DeleteAllEntries(NT_Inst inst);
/**
* Get Entry Information.
*
* Returns an array of entry information (name, entry type,
* and timestamp of last change to type/value). The results are optionally
* filtered by string prefix and entry type to only return a subset of all
@@ -560,6 +593,7 @@ std::vector<EntryInfo> GetEntryInfo(NT_Inst inst, const Twine& prefix,
/**
* Get Entry Information.
*
* Returns information about an entry (name, entry type,
* and timestamp of last change to type/value).
*
@@ -571,7 +605,7 @@ EntryInfo GetEntryInfo(NT_Entry entry);
/** @} */
/**
* @defgroup EntryListenerFunctions Entry Listener Functions
* @defgroup ntcore_entrylistener_func Entry Listener Functions
* @{
*/
@@ -605,6 +639,7 @@ NT_EntryListener AddEntryListener(StringRef prefix,
/**
* @copydoc AddEntryListener(StringRef, EntryListenerCallback, unsigned int)
*
* @param inst instance handle
*/
NT_EntryListener AddEntryListener(
@@ -627,10 +662,12 @@ NT_EntryListener AddEntryListener(
/**
* Create a entry listener poller.
*
* A poller provides a single queue of poll events. Events linked to this
* poller (using AddPolledEntryListener()) will be stored in the queue and
* must be collected by calling PollEntryListener().
* The returned handle must be destroyed with DestroyEntryListenerPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -639,6 +676,7 @@ NT_EntryListenerPoller CreateEntryListenerPoller(NT_Inst inst);
/**
* Destroy a entry listener poller. This will abort any blocked polling
* call and prevent additional events from being generated for this poller.
*
* @param poller poller handle
*/
void DestroyEntryListenerPoller(NT_EntryListenerPoller poller);
@@ -646,6 +684,7 @@ void DestroyEntryListenerPoller(NT_EntryListenerPoller poller);
/**
* Create a polled entry listener.
* The caller is responsible for calling PollEntryListener() to poll.
*
* @param poller poller handle
* @param prefix UTF-8 string prefix
* @param flags NotifyKind bitmask
@@ -658,6 +697,7 @@ NT_EntryListener AddPolledEntryListener(NT_EntryListenerPoller poller,
/**
* Create a polled entry listener.
* The caller is responsible for calling PollEntryListener() to poll.
*
* @param poller poller handle
* @param prefix UTF-8 string prefix
* @param flags NotifyKind bitmask
@@ -670,6 +710,7 @@ NT_EntryListener AddPolledEntryListener(NT_EntryListenerPoller poller,
* Get the next entry listener event. This blocks until the next event occurs.
* This is intended to be used with AddPolledEntryListener(); entry listeners
* created using AddEntryListener() will not be serviced through this function.
*
* @param poller poller handle
* @return Information on the entry listener events. Only returns empty if an
* error occurred (e.g. the instance was invalid or is shutting down).
@@ -681,6 +722,7 @@ std::vector<EntryNotification> PollEntryListener(NT_EntryListenerPoller poller);
* or it times out. This is intended to be used with AddPolledEntryListener();
* entry listeners created using AddEntryListener() will not be serviced
* through this function.
*
* @param poller poller handle
* @param timeout timeout, in seconds
* @param timed_out true if the timeout period elapsed (output)
@@ -696,12 +738,14 @@ std::vector<EntryNotification> PollEntryListener(NT_EntryListenerPoller poller,
* Cancel a PollEntryListener call. This wakes up a call to
* PollEntryListener for this poller and causes it to immediately return
* an empty array.
*
* @param poller poller handle
*/
void CancelPollEntryListener(NT_EntryListenerPoller poller);
/**
* Remove an entry listener.
*
* @param entry_listener Listener handle to remove
*/
void RemoveEntryListener(NT_EntryListener entry_listener);
@@ -711,6 +755,7 @@ void RemoveEntryListener(NT_EntryListener entry_listener);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -721,7 +766,7 @@ bool WaitForEntryListenerQueue(NT_Inst inst, double timeout);
/** @} */
/**
* @defgroup ConnectionListenerFunctions Connection Listener Functions
* @defgroup ntcore_connectionlistener_func Connection Listener Functions
* @{
*/
@@ -751,6 +796,7 @@ NT_ConnectionListener AddConnectionListener(ConnectionListenerCallback callback,
/**
* @copydoc AddConnectionListener(ConnectionListenerCallback, bool)
*
* @param inst instance handle
*/
NT_ConnectionListener AddConnectionListener(
@@ -760,10 +806,12 @@ NT_ConnectionListener AddConnectionListener(
/**
* Create a connection listener poller.
*
* A poller provides a single queue of poll events. Events linked to this
* poller (using AddPolledConnectionListener()) will be stored in the queue and
* must be collected by calling PollConnectionListener().
* The returned handle must be destroyed with DestroyConnectionListenerPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -772,6 +820,7 @@ NT_ConnectionListenerPoller CreateConnectionListenerPoller(NT_Inst inst);
/**
* Destroy a connection listener poller. This will abort any blocked polling
* call and prevent additional events from being generated for this poller.
*
* @param poller poller handle
*/
void DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller);
@@ -779,6 +828,7 @@ void DestroyConnectionListenerPoller(NT_ConnectionListenerPoller poller);
/**
* Create a polled connection listener.
* The caller is responsible for calling PollConnectionListener() to poll.
*
* @param poller poller handle
* @param immediate_notify notify listener of all existing connections
*/
@@ -790,6 +840,7 @@ NT_ConnectionListener AddPolledConnectionListener(
* disconnect occurs. This is intended to be used with
* AddPolledConnectionListener(); connection listeners created using
* AddConnectionListener() will not be serviced through this function.
*
* @param poller poller handle
* @return Information on the connection events. Only returns empty if an
* error occurred (e.g. the instance was invalid or is shutting down).
@@ -802,6 +853,7 @@ std::vector<ConnectionNotification> PollConnectionListener(
* disconnect occurs or it times out. This is intended to be used with
* AddPolledConnectionListener(); connection listeners created using
* AddConnectionListener() will not be serviced through this function.
*
* @param poller poller handle
* @param timeout timeout, in seconds
* @param timed_out true if the timeout period elapsed (output)
@@ -816,12 +868,14 @@ std::vector<ConnectionNotification> PollConnectionListener(
* Cancel a PollConnectionListener call. This wakes up a call to
* PollConnectionListener for this poller and causes it to immediately return
* an empty array.
*
* @param poller poller handle
*/
void CancelPollConnectionListener(NT_ConnectionListenerPoller poller);
/**
* Remove a connection listener.
*
* @param conn_listener Listener handle to remove
*/
void RemoveConnectionListener(NT_ConnectionListener conn_listener);
@@ -831,6 +885,7 @@ void RemoveConnectionListener(NT_ConnectionListener conn_listener);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -841,13 +896,14 @@ bool WaitForConnectionListenerQueue(NT_Inst inst, double timeout);
/** @} */
/**
* @defgroup RpcFunctions Remote Procedure Call Functions
* @defgroup ntcore_rpc_func Remote Procedure Call Functions
* @{
*/
/**
* Create a callback-based RPC entry point. Only valid to use on the server.
* The callback function will be called when the RPC is called.
*
* @param entry entry handle of RPC entry
* @param def RPC definition
* @param callback callback function; note the callback function must call
@@ -858,10 +914,12 @@ void CreateRpc(NT_Entry entry, StringRef def,
/**
* Create a RPC call poller. Only valid to use on the server.
*
* A poller provides a single queue of poll events. Events linked to this
* poller (using CreatePolledRpc()) will be stored in the queue and must be
* collected by calling PollRpc().
* The returned handle must be destroyed with DestroyRpcCallPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -870,6 +928,7 @@ NT_RpcCallPoller CreateRpcCallPoller(NT_Inst inst);
/**
* Destroy a RPC call poller. This will abort any blocked polling call and
* prevent additional events from being generated for this poller.
*
* @param poller poller handle
*/
void DestroyRpcCallPoller(NT_RpcCallPoller poller);
@@ -878,6 +937,7 @@ void DestroyRpcCallPoller(NT_RpcCallPoller poller);
* Create a polled RPC entry point. Only valid to use on the server.
* The caller is responsible for calling PollRpc() to poll for servicing
* incoming RPC calls.
*
* @param entry entry handle of RPC entry
* @param def RPC definition
* @param poller poller handle
@@ -890,6 +950,7 @@ void CreatePolledRpc(NT_Entry entry, StringRef def, NT_RpcCallPoller poller);
* RPC calls created using CreateRpc() will not be serviced through this
* function. Upon successful return, PostRpcResponse() must be called to
* send the return value to the caller.
*
* @param poller poller handle
* @return Information on the next RPC calls. Only returns empty if an error
* occurred (e.g. the instance was invalid or is shutting down).
@@ -902,6 +963,7 @@ std::vector<RpcAnswer> PollRpc(NT_RpcCallPoller poller);
* CreatePolledRpc(); RPC calls created using CreateRpc() will not be
* serviced through this function. Upon successful return,
* PostRpcResponse() must be called to send the return value to the caller.
*
* @param poller poller handle
* @param timeout timeout, in seconds
* @param timed_out true if the timeout period elapsed (output)
@@ -915,6 +977,7 @@ std::vector<RpcAnswer> PollRpc(NT_RpcCallPoller poller, double timeout,
/**
* Cancel a PollRpc call. This wakes up a call to PollRpc for this poller
* and causes it to immediately return an empty array.
*
* @param poller poller handle
*/
void CancelPollRpc(NT_RpcCallPoller poller);
@@ -924,6 +987,7 @@ void CancelPollRpc(NT_RpcCallPoller poller);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -935,6 +999,7 @@ bool WaitForRpcCallQueue(NT_Inst inst, double timeout);
* Post RPC response (return value) for a polled RPC.
* The rpc and call parameters should come from the RpcAnswer returned
* by PollRpc().
*
* @param entry entry handle of RPC entry (from RpcAnswer)
* @param call RPC call handle (from RpcAnswer)
* @param result result raw data that will be provided to remote caller
@@ -947,6 +1012,7 @@ bool PostRpcResponse(NT_Entry entry, NT_RpcCall call, StringRef result);
* This function is non-blocking. Either GetRpcResult() or
* CancelRpcResult() must be called to either get or ignore the result of
* the call.
*
* @param entry entry handle of RPC entry
* @param params parameter
* @return RPC call handle (for use with GetRpcResult() or
@@ -957,6 +1023,7 @@ NT_RpcCall CallRpc(NT_Entry entry, StringRef params);
/**
* Get the result (return value) of a RPC call. This function blocks until
* the result is received.
*
* @param entry entry handle of RPC entry
* @param call RPC call handle returned by CallRpc()
* @param result received result (output)
@@ -967,6 +1034,7 @@ bool GetRpcResult(NT_Entry entry, NT_RpcCall call, std::string* result);
/**
* Get the result (return value) of a RPC call. This function blocks until
* the result is received or it times out.
*
* @param entry entry handle of RPC entry
* @param call RPC call handle returned by CallRpc()
* @param result received result (output)
@@ -979,6 +1047,7 @@ bool GetRpcResult(NT_Entry entry, NT_RpcCall call, std::string* result,
/**
* Ignore the result of a RPC call. This function is non-blocking.
*
* @param entry entry handle of RPC entry
* @param call RPC call handle returned by CallRpc()
*/
@@ -986,6 +1055,7 @@ void CancelRpcResult(NT_Entry entry, NT_RpcCall call);
/**
* Pack a RPC version 1 definition.
*
* @param def RPC version 1 definition
* @return Raw packed bytes.
*/
@@ -994,6 +1064,7 @@ std::string PackRpcDefinition(const RpcDefinition& def);
/**
* Unpack a RPC version 1 definition. This can be used for introspection or
* validation.
*
* @param packed raw packed bytes
* @param def RPC version 1 definition (output)
* @return True if successfully unpacked, false otherwise.
@@ -1002,6 +1073,7 @@ bool UnpackRpcDefinition(StringRef packed, RpcDefinition* def);
/**
* Pack RPC values as required for RPC version 1 definition messages.
*
* @param values array of values to pack
* @return Raw packed bytes.
*/
@@ -1009,6 +1081,7 @@ std::string PackRpcValues(ArrayRef<std::shared_ptr<Value>> values);
/**
* Unpack RPC values as required for RPC version 1 definition messages.
*
* @param packed raw packed bytes
* @param types array of data types (as provided in the RPC definition)
* @return Array of values.
@@ -1019,7 +1092,7 @@ std::vector<std::shared_ptr<Value>> UnpackRpcValues(StringRef packed,
/** @} */
/**
* @defgroup NetworkFunctions Client/Server Functions
* @defgroup ntcore_network_func Client/Server Functions
* @{
*/
@@ -1027,6 +1100,7 @@ std::vector<std::shared_ptr<Value>> UnpackRpcValues(StringRef packed,
* 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
*/
WPI_DEPRECATED("use NT_Inst function instead")
@@ -1034,12 +1108,14 @@ void SetNetworkIdentity(StringRef name);
/**
* @copydoc SetNetworkIdentity(StringRef)
*
* @param inst instance handle
*/
void SetNetworkIdentity(NT_Inst inst, const Twine& name);
/**
* Get the current network mode.
*
* @return Bitmask of NT_NetworkMode.
*/
WPI_DEPRECATED("use NT_Inst function instead")
@@ -1047,6 +1123,7 @@ unsigned int GetNetworkMode();
/**
* Get the current network mode.
*
* @param inst instance handle
* @return Bitmask of NT_NetworkMode.
*/
@@ -1067,6 +1144,7 @@ void StartServer(StringRef persist_filename, const char* listen_address,
/**
* @copydoc StartServer(StringRef, const char*, unsigned int)
*
* @param inst instance handle
*/
void StartServer(NT_Inst inst, const Twine& persist_filename,
@@ -1080,6 +1158,7 @@ void StopServer();
/**
* @copydoc StopServer()
*
* @param inst instance handle
*/
void StopServer(NT_Inst inst);
@@ -1110,18 +1189,21 @@ void StartClient(ArrayRef<std::pair<StringRef, unsigned int>> servers);
/**
* @copydoc StartClient()
*
* @param inst instance handle
*/
void StartClient(NT_Inst inst);
/**
* @copydoc StartClient(const char*, unsigned int)
*
* @param inst instance handle
*/
void StartClient(NT_Inst inst, const char* server_name, unsigned int port);
/**
* @copydoc StartClient(ArrayRef<std::pair<StringRef, unsigned int>>)
*
* @param inst instance handle
*/
void StartClient(NT_Inst inst,
@@ -1169,12 +1251,14 @@ void SetServer(ArrayRef<std::pair<StringRef, unsigned int>> servers);
/**
* @copydoc SetServer(const char*, unsigned int)
*
* @param inst instance handle
*/
void SetServer(NT_Inst inst, const char* server_name, unsigned int port);
/**
* @copydoc SetServer(ArrayRef<std::pair<StringRef, unsigned int>>)
*
* @param inst instance handle
*/
void SetServer(NT_Inst inst,
@@ -1212,6 +1296,7 @@ void StopDSClient();
/**
* @copydoc StopDSClient()
*
* @param inst instance handle
*/
void StopDSClient(NT_Inst inst);
@@ -1231,12 +1316,14 @@ void SetUpdateRate(double interval);
/**
* @copydoc SetUpdateRate(double)
*
* @param inst instance handle
*/
void SetUpdateRate(NT_Inst inst, double interval);
/**
* Flush Entries.
*
* Forces an immediate flush of all local entry changes to network.
* Normally this is done on a regularly scheduled interval (see
* SetUpdateRate()).
@@ -1266,12 +1353,14 @@ std::vector<ConnectionInfo> GetConnections();
/**
* @copydoc GetConnections()
*
* @param inst instance handle
*/
std::vector<ConnectionInfo> GetConnections(NT_Inst inst);
/**
* Return whether or not the instance is connected to another node.
*
* @param inst instance handle
* @return True if connected.
*/
@@ -1280,7 +1369,7 @@ bool IsConnected(NT_Inst inst);
/** @} */
/**
* @defgroup FileFunctions File Save/Load Functions
* @defgroup ntcore_file_func File Save/Load Functions
* @{
*/
@@ -1288,6 +1377,7 @@ bool IsConnected(NT_Inst inst);
* 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
*/
@@ -1304,6 +1394,7 @@ const char* SavePersistent(NT_Inst inst, const Twine& filename);
* 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
@@ -1315,6 +1406,7 @@ const char* LoadPersistent(
/**
* @copydoc LoadPersistent(StringRef, std::function<void(size_t, const
* char*)>)
*
* @param inst instance handle
*/
const char* LoadPersistent(
@@ -1324,6 +1416,7 @@ const char* LoadPersistent(
/**
* Save table values to a file. The file format used is identical to
* that used for SavePersistent.
*
* @param inst instance handle
* @param filename filename
* @param prefix save only keys starting with this prefix
@@ -1335,6 +1428,7 @@ const char* SaveEntries(NT_Inst inst, const Twine& filename,
/**
* Load table values from a file. The file format used is identical to
* that used for SavePersistent / LoadPersistent.
*
* @param inst instance handle
* @param filename filename
* @param prefix load only keys starting with this prefix
@@ -1348,7 +1442,7 @@ const char* LoadEntries(NT_Inst inst, const Twine& filename,
/** @} */
/**
* @defgroup UtilityFunctions Utility Functions
* @defgroup ntcore_utility_func Utility Functions
* @{
*/
@@ -1356,6 +1450,7 @@ const char* LoadEntries(NT_Inst inst, const Twine& filename,
* Returns monotonic current time in 1 us increments.
* This is the same time base used for entry and connection timestamps.
* This function is a compatibility wrapper around wpi::Now().
*
* @return Timestamp
*/
uint64_t Now();
@@ -1363,12 +1458,13 @@ uint64_t Now();
/** @} */
/**
* @defgroup LoggerFunctions Logger Functions
* @defgroup ntcore_logger_func Logger Functions
* @{
*/
/**
* Log function.
*
* @param level log level of the message (see NT_LogLevel)
* @param file origin source filename
* @param line origin source line number
@@ -1411,6 +1507,7 @@ NT_Logger AddLogger(NT_Inst inst,
/**
* Create a log poller. A poller provides a single queue of poll events.
* The returned handle must be destroyed with DestroyLoggerPoller().
*
* @param inst instance handle
* @return poller handle
*/
@@ -1419,6 +1516,7 @@ NT_LoggerPoller CreateLoggerPoller(NT_Inst inst);
/**
* Destroy a log poller. This will abort any blocked polling call and prevent
* additional events from being generated for this poller.
*
* @param poller poller handle
*/
void DestroyLoggerPoller(NT_LoggerPoller poller);
@@ -1427,6 +1525,7 @@ void DestroyLoggerPoller(NT_LoggerPoller poller);
* Set the log level for a log poller. Events will only be generated for
* log messages with level greater than or equal to min_level and less than or
* equal to max_level; messages outside this range will be silently ignored.
*
* @param poller poller handle
* @param min_level minimum log level
* @param max_level maximum log level
@@ -1437,6 +1536,7 @@ NT_Logger AddPolledLogger(NT_LoggerPoller poller, unsigned int min_level,
/**
* Get the next log event. This blocks until the next log occurs.
*
* @param poller poller handle
* @return Information on the log events. Only returns empty if an error
* occurred (e.g. the instance was invalid or is shutting down).
@@ -1446,6 +1546,7 @@ std::vector<LogMessage> PollLogger(NT_LoggerPoller poller);
/**
* Get the next log event. This blocks until the next log occurs or it times
* out.
*
* @param poller poller handle
* @param timeout timeout, in seconds
* @param timed_out true if the timeout period elapsed (output)
@@ -1459,12 +1560,14 @@ std::vector<LogMessage> PollLogger(NT_LoggerPoller poller, double timeout,
/**
* Cancel a PollLogger call. This wakes up a call to PollLogger for this
* poller and causes it to immediately return an empty array.
*
* @param poller poller handle
*/
void CancelPollLogger(NT_LoggerPoller poller);
/**
* Remove a logger.
*
* @param logger Logger handle to remove
*/
void RemoveLogger(NT_Logger logger);
@@ -1474,6 +1577,7 @@ void RemoveLogger(NT_Logger logger);
* 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 inst instance handle
* @param timeout timeout, in seconds. Set to 0 for non-blocking behavior,
* or a negative value to block indefinitely
@@ -1481,6 +1585,7 @@ void RemoveLogger(NT_Logger logger);
*/
bool WaitForLoggerQueue(NT_Inst inst, double timeout);
/** @} */
/** @} */
inline bool RpcAnswer::PostResponse(StringRef result) const {