From 1b450d0a854af44a3b587850a7743528fe41c19f Mon Sep 17 00:00:00 2001
From: kevin <kevin@larke.org>
Date: Fri, 20 Sep 2024 18:16:28 -0400
Subject: [PATCH] cwIoFlowCtl.h/cpp : 1. Implemented program_preset_count() and
 program_preset_label(). 2. Implemented program_initialize().

---
 cwIoFlowCtl.cpp | 75 +++++++++++++++++++++++++++++--------------------
 cwIoFlowCtl.h   | 26 +++++++++--------
 2 files changed, 60 insertions(+), 41 deletions(-)

diff --git a/cwIoFlowCtl.cpp b/cwIoFlowCtl.cpp
index 09b19dc..738f06c 100644
--- a/cwIoFlowCtl.cpp
+++ b/cwIoFlowCtl.cpp
@@ -640,15 +640,6 @@ cw::rc_t    cw::io_flow_ctl::program_load(  handle_t h, unsigned pgm_idx )
   // setup the control record for each external device known to the IO interface
   _setup_generic_device_array(p);
   
-  // create the flow network
-  if((rc = initialize( p->flowH,
-                       p->deviceA,
-                       p->deviceN)) != kOkRC )
-  {
-    rc = cwLogError(rc,"Network create failed.");
-    goto errLabel;
-  }
-
   p->pgm_idx = pgm_idx;
   p->done_fl = false;
 
@@ -662,11 +653,6 @@ unsigned    cw::io_flow_ctl::program_current_index( handle_t h )
   return p->pgm_idx;
 }
 
-cw::rc_t   cw::io_flow_ctl::program_reset( handle_t h )
-{
-  return kOkRC;
-}
-
 bool        cw::io_flow_ctl::is_program_nrt( handle_t h )
 {
   io_flow_ctl_t* p      = _handleToPtr(h);
@@ -687,6 +673,50 @@ errLabel:
   return nrt_fl;
 }
 
+unsigned    cw::io_flow_ctl::program_preset_count( handle_t h )
+{
+  io_flow_ctl_t* p      = _handleToPtr(h);
+  
+  if(!p->flowH.isValid() || _validate_pgm_idx(p,p->pgm_idx) != kOkRC )
+    return 0;
+  
+  return preset_count(p->flowH);
+}
+
+const char* cw::io_flow_ctl::program_preset_title( handle_t h, unsigned preset_idx )
+{
+  io_flow_ctl_t* p      = _handleToPtr(h);
+  
+  if(!p->flowH.isValid() || _validate_pgm_idx(p,p->pgm_idx) != kOkRC )
+    return nullptr;
+  return preset_label(p->flowH,preset_idx);
+}
+
+cw::rc_t cw::io_flow_ctl::program_initialize( handle_t h, unsigned preset_idx )
+{
+  rc_t rc = kOkRC;
+  io_flow_ctl_t* p = _handleToPtr(h);
+
+  if( p->pgm_idx == kInvalidIdx || p->done_fl || !p->flowH.isValid() )
+  {
+    cwLogError(kInvalidStateRC,"A valid pre-initialized program is not loaded.");
+    goto errLabel;
+  }
+  
+  // create the flow network
+  if((rc = initialize( p->flowH,
+                       p->deviceA,
+                       p->deviceN,
+                       preset_idx )) != kOkRC )
+  {
+    rc = cwLogError(rc,"Network create failed.");
+    goto errLabel;
+  }
+
+errLabel:
+  return rc;
+}
+
 cw::rc_t    cw::io_flow_ctl::exec_nrt( handle_t h )
 {
   rc_t           rc = kOkRC;
@@ -722,21 +752,6 @@ errLabel:
   return rc;
 }
 
-unsigned    cw::io_flow_ctl::preset_count( handle_t h )
-{
-  return 0;
-}
-
-const char* cw::io_flow_ctl::preset_title( handle_t h, unsigned preset_idx )
-{
-  return nullptr;
-}
-
-cw::rc_t    cw::io_flow_ctl::preset_apply( handle_t h, unsigned preset_idx )
-{
-  return kOkRC;
-}
-
 cw::rc_t cw::io_flow_ctl::exec( handle_t h, const io::msg_t& msg )
 {
   rc_t           rc = kOkRC;
@@ -761,7 +776,7 @@ bool cw::io_flow_ctl::is_executable( handle_t h )
 {
   io_flow_ctl_t* p  = _handleToPtr(h);
 
-  // A program must be loaded and execution cannot be complete
+  // A program must be loaded, initialized and execution cannot be complete
   return p->pgm_idx != kInvalidIdx && p->done_fl==false;
 }
 
diff --git a/cwIoFlowCtl.h b/cwIoFlowCtl.h
index 51ac7be..2ebc7ef 100644
--- a/cwIoFlowCtl.h
+++ b/cwIoFlowCtl.h
@@ -12,34 +12,38 @@ namespace cw
     rc_t create(  handle_t& hRef, io::handle_t ioH, const object_t* flow_cfg );
     rc_t destroy( handle_t& hRef );
 
+    // Query the available programs from the 'flow_cfg' file.
     unsigned    program_count( handle_t h);
     const char* program_title( handle_t h, unsigned pgm_idx );
     unsigned    program_index( handle_t h, const char* pgm_title);
-    bool        program_is_nrt(handle_t h, unsigned pgm_idx);
+
+    // Create the parse the program but do not instantiate the network.
     rc_t        program_load(  handle_t h, unsigned pgm_idx );
 
     // Return the index of the currently loaded program or kInvalidIdx if no program is loaded.
     unsigned    program_current_index( handle_t h );
 
-    // Reset the the current program to it's initial state.
-    rc_t        program_reset( handle_t h );
-    
     // Is the currently loaded program in non-real-time mode
     bool        is_program_nrt( handle_t h );
 
+    // Return the count of network presets and the associated labels for the currently loaded program.
+    unsigned    program_preset_count( handle_t h );
+    const char* program_preset_title( handle_t h, unsigned preset_idx );
+
+    // Create the network and prepare to enter runtime.
+    rc_t        program_initialize( handle_t h, unsigned preset_idx=kInvalidIdx );
+    
     // Execute the currently loaded non-real-time program to completion.
     rc_t        exec_nrt( handle_t h );
     
-    // Return the count of network presets associated with the current program.
-    unsigned    preset_count( handle_t h );
-    const char* preset_title( handle_t h, unsigned preset_idx );
-    rc_t        preset_apply( handle_t h, unsigned preset_idx );
-
-
-    // Handle an incoming IO msg.
+    // Handle an incoming IO msg. This is the main point of entry for executing
+    // real-time programs.
     rc_t exec( handle_t h, const io::msg_t& msg );
 
+    // Is the current program loaded, initialized and not yet complete.
     bool is_executable( handle_t h );
+
+    // The current program has completed.
     bool is_exec_complete( handle_t h );
 
     void report( handle_t h );