[ntcore] Various NT4 fixes (#4474)

* TopicListener: Fix Add() return values
* Update PubSubOption poll storage documentation
* Update NetworkTableEntry::GetValue() doc
* Add documentation regarding asynchronous callbacks
* Unpublish entry: set publisher to nullptr
* Implement ValueListenerPoller default constructor
* Remove SetNetworkIdentity, make parameter to StartClient
* URI-escape client ID, improve error message
* Add connected message with client id; also improve disconnected message a bit
* Handle SetServers either before or after StartClient
* Fix client use-after-free; also delay reconnect after disconnect to rate limit
* Don't re-announce to already subscribed client; we especially don't want to send the last value again
* Always accept in-order sets, only use timestamp for tiebreak
* Fix LocalStorage::StartNetwork race
* Remove unused/unimplemented function

Also:
* [glass] Remove debug print
* [glass] Fix mpack string decoding
* [cameraserver] Fix up startclient

ntcore/src/main/native/include/networktables/ConnectionListener.h

@@ -15,7 +15,9 @@ class NetworkTableInstance;
 
 /**
  * Connection listener. This calls back to a callback function when a connection
- * change occurs.
+ * change occurs. The callback function is called asynchronously on a separate
+ * thread, so it's important to use synchronization or atomics when accessing
+ * any shared state from the callback function.
  */
 class ConnectionListener final {
  public:

ntcore/src/main/native/include/networktables/NetworkTableEntry.h

@@ -112,9 +112,10 @@ class NetworkTableEntry final {
   int64_t GetLastChange() const;
 
   /**
-   * Gets the entry's value. If the entry does not exist, returns nullptr.
+   * Gets the entry's value. If the entry does not exist, returns an empty
+   * value.
    *
-   * @return the entry's value or nullptr if it does not exist.
+   * @return the entry's value or an empty value if it does not exist.
    */
   Value GetValue() const;
 

ntcore/src/main/native/include/networktables/NetworkTableInstance.h

@@ -383,16 +383,6 @@ class NetworkTableInstance final {
    * @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(std::string_view name);
-
   /**
    * Get the current network mode.
    *
@@ -436,14 +426,18 @@ class NetworkTableInstance final {
   /**
    * Starts a NT3 client.  Use SetServer or SetServerTeam to set the server name
    * and port.
+   *
+   * @param identity  network identity to advertise (cannot be empty string)
    */
-  void StartClient3();
+  void StartClient3(std::string_view identity);
 
   /**
    * Starts a NT4 client.  Use SetServer or SetServerTeam to set the server name
    * and port.
+   *
+   * @param identity  network identity to advertise (cannot be empty string)
    */
-  void StartClient4();
+  void StartClient4(std::string_view identity);
 
   /**
    * Stops the client if it is running.

ntcore/src/main/native/include/networktables/NetworkTableInstance.inc

@@ -87,10 +87,6 @@ inline void NetworkTableInstance::RemoveConnectionListener(
   ::nt::RemoveConnectionListener(conn_listener);
 }
 
-inline void NetworkTableInstance::SetNetworkIdentity(std::string_view name) {
-  ::nt::SetNetworkIdentity(m_handle, name);
-}
-
 inline unsigned int NetworkTableInstance::GetNetworkMode() const {
   return ::nt::GetNetworkMode(m_handle);
 }
@@ -114,12 +110,12 @@ inline void NetworkTableInstance::StopServer() {
   ::nt::StopServer(m_handle);
 }
 
-inline void NetworkTableInstance::StartClient3() {
-  ::nt::StartClient3(m_handle);
+inline void NetworkTableInstance::StartClient3(std::string_view identity) {
+  ::nt::StartClient3(m_handle, identity);
 }
 
-inline void NetworkTableInstance::StartClient4() {
-  ::nt::StartClient4(m_handle);
+inline void NetworkTableInstance::StartClient4(std::string_view identity) {
+  ::nt::StartClient4(m_handle, identity);
 }
 
 inline void NetworkTableInstance::StopClient() {

ntcore/src/main/native/include/networktables/TopicListener.h

@@ -66,7 +66,9 @@ struct TopicListenerFlags {
 
 /**
  * Topic change listener. This calls back to a callback function when a topic
- * change matching the specified mask occurs.
+ * change matching the specified mask occurs. The callback function is called
+ * asynchronously on a separate thread, so it's important to use synchronization
+ * or atomics when accessing any shared state from the callback function.
  */
 class TopicListener final {
  public:
@@ -202,7 +204,7 @@ class TopicListenerPoller final {
    * @param mask Bitmask of TopicListenerFlags values
    * @return Listener handle
    */
-  NT_ValueListener Add(const Subscriber& subscriber, unsigned int mask);
+  NT_TopicListener Add(const Subscriber& subscriber, unsigned int mask);
 
   /**
    * Start listening to topic changes on a subscriber.
@@ -211,7 +213,7 @@ class TopicListenerPoller final {
    * @param mask Bitmask of TopicListenerFlags values
    * @return Listener handle
    */
-  NT_ValueListener Add(const MultiSubscriber& subscriber, unsigned int mask);
+  NT_TopicListener Add(const MultiSubscriber& subscriber, unsigned int mask);
 
   /**
    * Start listening to topic changes on an entry.
@@ -220,7 +222,7 @@ class TopicListenerPoller final {
    * @param mask Bitmask of TopicListenerFlags values
    * @return Listener handle
    */
-  NT_ValueListener Add(const NetworkTableEntry& entry, unsigned int mask);
+  NT_TopicListener Add(const NetworkTableEntry& entry, unsigned int mask);
 
   /**
    * Remove a listener.

ntcore/src/main/native/include/networktables/ValueListener.h

@@ -48,7 +48,9 @@ struct ValueListenerFlags {
 
 /**
  * Value change listener. This calls back to a callback function when a value
- * change matching the specified mask occurs.
+ * change matching the specified mask occurs. The callback function is called
+ * asynchronously on a separate thread, so it's important to use synchronization
+ * or atomics when accessing any shared state from the callback function.
  */
 class ValueListener final {
  public:
@@ -120,7 +122,7 @@ class ValueListener final {
  */
 class ValueListenerPoller final {
  public:
-  ValueListenerPoller();
+  ValueListenerPoller() = default;
 
   /**
    * Construct a value listener poller.
@@ -196,7 +198,7 @@ class ValueListenerPoller final {
   std::vector<ValueNotification> ReadQueue();
 
  private:
-  NT_ValueListenerPoller m_handle;
+  NT_ValueListenerPoller m_handle{0};
 };
 
 }  // namespace nt

ntcore/src/main/native/include/ntcore_c.h

@@ -198,8 +198,7 @@ struct NT_TopicInfo {
 /** NetworkTables Connection Information */
 struct NT_ConnectionInfo {
   /**
-   * The remote identifier (as set on the remote node by
-   * NetworkTableInstance::SetNetworkIdentity() or nt::SetNetworkIdentity()).
+   * The remote identifier (as set on the remote node by NT_StartClient4().
    */
   struct NT_String remote_id;
 
@@ -1114,17 +1113,6 @@ void NT_RemoveConnectionListener(NT_ConnectionListener conn_listener);
  * @{
  */
 
-/**
- * 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
- */
-void NT_SetNetworkIdentity(NT_Inst inst, const char* name, size_t name_len);
-
 /**
  * Get the current network mode.
  *
@@ -1172,17 +1160,19 @@ void NT_StopServer(NT_Inst inst);
  * Starts a NT3 client.  Use NT_SetServer or NT_SetServerTeam to set the server
  * name and port.
  *
- * @param inst  instance handle
+ * @param inst      instance handle
+ * @param identity  network identity to advertise (cannot be empty string)
  */
-void NT_StartClient3(NT_Inst inst);
+void NT_StartClient3(NT_Inst inst, const char* identity);
 
 /**
  * Starts a NT4 client.  Use NT_SetServer or NT_SetServerTeam to set the server
  * name and port.
  *
- * @param inst  instance handle
+ * @param inst      instance handle
+ * @param identity  network identity to advertise (cannot be empty string)
  */
-void NT_StartClient4(NT_Inst inst);
+void NT_StartClient4(NT_Inst inst, const char* identity);
 
 /**
  * Stops the client if it is running.

ntcore/src/main/native/include/ntcore_cpp.h

@@ -74,7 +74,7 @@ struct TopicInfo {
 struct ConnectionInfo {
   /**
    * The remote identifier (as set on the remote node by
-   * NetworkTableInstance::SetNetworkIdentity() or nt::SetNetworkIdentity()).
+   * NetworkTableInstance::StartClient4() or nt::StartClient4()).
    */
   std::string remote_id;
 
@@ -292,7 +292,7 @@ class PubSubOption {
   /**
    * Polling storage for subscription. Specifies the maximum number of updates
    * NetworkTables should store between calls to the subscriber's poll()
-   * function. Defaults to 1 if logging is false, 20 if logging is true.
+   * function. Defaults to 1 if SendAll is false, 20 if SendAll is true.
    *
    * @param depth number of entries to save for polling.
    * @return option
@@ -1007,16 +1007,6 @@ void RemoveConnectionListener(NT_ConnectionListener conn_listener);
  * @{
  */
 
-/**
- * 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 inst      instance handle
- * @param name      identity to advertise
- */
-void SetNetworkIdentity(NT_Inst inst, std::string_view name);
-
 /**
  * Get the current network mode.
  *
@@ -1064,17 +1054,19 @@ void StopServer(NT_Inst inst);
  * Starts a NT3 client.  Use SetServer or SetServerTeam to set the server name
  * and port.
  *
- * @param inst  instance handle
+ * @param inst      instance handle
+ * @param identity  network identity to advertise (cannot be empty string)
  */
-void StartClient3(NT_Inst inst);
+void StartClient3(NT_Inst inst, std::string_view identity);
 
 /**
  * Starts a NT4 client.  Use SetServer or SetServerTeam to set the server name
  * and port.
  *
- * @param inst  instance handle
+ * @param inst      instance handle
+ * @param identity  network identity to advertise (cannot be empty string)
  */
-void StartClient4(NT_Inst inst);
+void StartClient4(NT_Inst inst, std::string_view identity);
 
 /**
  * Stops the client if it is running.