cscore: Add connection strategy to sources (#1252)

By default, sources automatically manage their connection based on whether
any sinks are connected.  This change allows the user to keep a connection
open or force it closed regardless of the number of connected sinks.

cscore/src/main/native/include/cscore_c.h

@@ -178,6 +178,27 @@ enum CS_TelemetryKind {
   CS_SOURCE_FRAMES_RECEIVED = 2
 };
 
+/** Connection strategy */
+enum CS_ConnectionStrategy {
+  /**
+   * Automatically connect or disconnect based on whether any sinks are
+   * connected to this source.  This is the default behavior.
+   */
+  CS_CONNECTION_AUTO_MANAGE = 0,
+
+  /**
+   * Try to keep the connection open regardless of whether any sinks are
+   * connected.
+   */
+  CS_CONNECTION_KEEP_OPEN,
+
+  /**
+   * Never open the connection.  If this is set when the connection is open,
+   * close the connection.
+   */
+  CS_CONNECTION_FORCE_CLOSE
+};
+
 /**
  * Listener event
  */
@@ -245,7 +266,11 @@ enum CS_SourceKind CS_GetSourceKind(CS_Source source, CS_Status* status);
 char* CS_GetSourceName(CS_Source source, CS_Status* status);
 char* CS_GetSourceDescription(CS_Source source, CS_Status* status);
 uint64_t CS_GetSourceLastFrameTime(CS_Source source, CS_Status* status);
+void CS_SetSourceConnectionStrategy(CS_Source source,
+                                    enum CS_ConnectionStrategy strategy,
+                                    CS_Status* status);
 CS_Bool CS_IsSourceConnected(CS_Source source, CS_Status* status);
+CS_Bool CS_IsSourceEnabled(CS_Source source, CS_Status* status);
 CS_Property CS_GetSourceProperty(CS_Source source, const char* name,
                                  CS_Status* status);
 CS_Property* CS_EnumerateSourceProperties(CS_Source source, int* count,

cscore/src/main/native/include/cscore_cpp.h

@@ -203,7 +203,11 @@ wpi::StringRef GetSourceDescription(CS_Source source,
                                     wpi::SmallVectorImpl<char>& buf,
                                     CS_Status* status);
 uint64_t GetSourceLastFrameTime(CS_Source source, CS_Status* status);
+void SetSourceConnectionStrategy(CS_Source source,
+                                 CS_ConnectionStrategy strategy,
+                                 CS_Status* status);
 bool IsSourceConnected(CS_Source source, CS_Status* status);
+bool IsSourceEnabled(CS_Source source, CS_Status* status);
 CS_Property GetSourceProperty(CS_Source source, const wpi::Twine& name,
                               CS_Status* status);
 wpi::ArrayRef<CS_Property> EnumerateSourceProperties(

cscore/src/main/native/include/cscore_oo.h

@@ -106,6 +106,27 @@ class VideoSource {
     kCv = CS_SOURCE_CV
   };
 
+  /** Connection strategy.  Used for SetConnectionStrategy(). */
+  enum ConnectionStrategy {
+    /**
+     * Automatically connect or disconnect based on whether any sinks are
+     * connected to this source.  This is the default behavior.
+     */
+    kConnectionAutoManage = CS_CONNECTION_AUTO_MANAGE,
+
+    /**
+     * Try to keep the connection open regardless of whether any sinks are
+     * connected.
+     */
+    kConnectionKeepOpen = CS_CONNECTION_KEEP_OPEN,
+
+    /**
+     * Never open the connection.  If this is set when the connection is open,
+     * close the connection.
+     */
+    kConnectionForceClose = CS_CONNECTION_FORCE_CLOSE
+  };
+
   VideoSource() noexcept : m_handle(0) {}
   VideoSource(const VideoSource& source);
   VideoSource(VideoSource&& other) noexcept;
@@ -146,11 +167,30 @@ class VideoSource {
    */
   uint64_t GetLastFrameTime() const;
 
+  /**
+   * Sets the connection strategy.  By default, the source will automatically
+   * connect or disconnect based on whether any sinks are connected.
+   *
+   * <p>This function is non-blocking; look for either a connection open or
+   * close event or call IsConnected() to determine the connection state.
+   *
+   * @param strategy connection strategy (auto, keep open, or force close)
+   */
+  void SetConnectionStrategy(ConnectionStrategy strategy);
+
   /**
    * Is the source currently connected to whatever is providing the images?
    */
   bool IsConnected() const;
 
+  /**
+   * Gets source enable status.  This is determined with a combination of
+   * connection strategy and the number of sinks connected.
+   *
+   * @return True if enabled, false otherwise.
+   */
+  bool IsEnabled() const;
+
   /** Get a property.
    *
    * @param name Property name

cscore/src/main/native/include/cscore_oo.inl

@@ -116,11 +116,23 @@ inline uint64_t VideoSource::GetLastFrameTime() const {
   return GetSourceLastFrameTime(m_handle, &m_status);
 }
 
+inline void VideoSource::SetConnectionStrategy(ConnectionStrategy strategy) {
+  m_status = 0;
+  SetSourceConnectionStrategy(
+      m_handle, static_cast<CS_ConnectionStrategy>(static_cast<int>(strategy)),
+      &m_status);
+}
+
 inline bool VideoSource::IsConnected() const {
   m_status = 0;
   return IsSourceConnected(m_handle, &m_status);
 }
 
+inline bool VideoSource::IsEnabled() const {
+  m_status = 0;
+  return IsSourceEnabled(m_handle, &m_status);
+}
+
 inline VideoProperty VideoSource::GetProperty(const wpi::Twine& name) {
   m_status = 0;
   return VideoProperty{GetSourceProperty(m_handle, name, &m_status)};