Changes between Initial Version and Version 1 of Old/Documentation/OTG/FuncSpec/UserInterface

Timestamp:

Sep 26, 2005, 3:56:18 PM (19 years ago)

Author:

zhibinwu

Comment:

—

Old/Documentation/OTG/FuncSpec/UserInterface

@@ +1 @@
+[wiki:WikiStart Orbit] > [wiki:OTG OTG] > [wiki:OTG/FuncSpec Function Specifications] > User Interface
+
+= Function Specification: User Interface Design =
+
+User Interace provides a command shell to users. User can specify important program arguments in a standard command line format. "--option <arg>".
+
+== Design Requirement ==
+The following principles of the design should be respected:
+ * User only need to give command-line options once to start the program. A step-by-step configuraton tends to be confusing, error-prone and complicates fault-handling.
+ * Configuration file shall not be used. (difficult to maintain)
+ * Run-time argument change must be supported whenever possible.
+ * In the run-time, user comamnd inputs can only change one parameter a time. (multiple changes at the same time might lead mutual conflicting)
+
+== Brief introduction abou using POPT ==
+
+The OTG software uses POPT library to simplify the design of user interface. To use POPT, 
+An "options" structure has to be defined first.
+{{{
+struct poptOption options[] = {
+  POPT_AUTOHELP
+  { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "Port" },
+  { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "Generator" },
+  { "protocol", '\0', POPT_ARG_STRING, NULL, 0, "Name of protocol"},
+  { "generator", '\0', POPT_ARG_STRING, NULL, 0, "Name of generator"},
+  { "debuglog", '\0', POPT_ARG_STRING, NULL, 0, "Filename of Measurements Log"},
+  { "exit", '\0', POPT_ARG_NONE, NULL, 1, "Stop the generator and exit" },
+  { "pause", '\0', POPT_ARG_NONE, NULL, 2, "pause the generator and exit" },
+  { "resume", '\0', POPT_ARG_NONE, NULL, 3, "resume the generator" },
+  { NULL, 0, 0, NULL, 0 }
+};
+}}}
+
+then, use a while loop to parse all given option arguments. Whenever an option name matches one of the options defined in the options array, the "poptGetNextOpt" fucntion call will return a value. Different options return differnt valuse. This occurs repetitively until the value returns -1. So, In "case" of differnt value, different handling routing should be proceeded.
+{{{
+  int rc;
+  while ((rc = poptGetNextOpt(optCon)) > 0) {
+
+        if (rc == 1) {// Stop
+          str->exitStream();
+          exit(0);  //exit terminate process and all its threads
+        }
+        else if (rc == 2)
+        { 
+          str->pauseStream();         
+        }
+        else if (rc==3)
+        {
+          str->resumeStream();
+        }     
+  };
+  if (rc < -1) {
+    cerr << "ERROR: " << poptBadOption(optCon, POPT_BADOPTION_NOALIAS)
+         << " (" << poptStrerror(rc) << ")" << endl;
+  }
+  poptFreeContext(optCon);
+  return rc;    
+}}}
+
+== OTG User Interface == 
+
+In OTG program, first-tier options are following 
+ * protocol, generator, debuglog
+"protocol" and "generator" must be parsed correctly before other arguements related to them can be understood. "debuglog" is used only for turning on the local logging of measurements. Because first-tier options are pivotal and governing 2nd-tier options in the program, run-time changes for them are impossible.
+
+Correspondingly, three fucntions are used in parsing options:
+ * parseOptionsPhase1
+ * parseOptionsPhase2
+ * parseRuntimeOptions
+
+''parseOptionsPhase1'' is used to set values for variables corresponding to first-tier arguments
+Because both Port and Generator are vitual base class, a certain type of Port and Generator objects will be created based on those variables.
+Second-tier options are parsed by ''parseOptionsPhase2''. Certain properties of newly created Port and Generator objects will be set.
+Finally, ''parseRuntimeOptions'' will parse run-time user input to change a certain set of parameters.
+For initial shell user inputs, ''argc'' and ''argv'' are automatically provided by standard C. So, we pass them to POPT function directly.
+But for run-time user inputs, a special char* variable ''msg'' is taken as the parameter. The msg contain the setting for only one options and either in "--option <arg>" format or without leading hyphons.
+
+== OTR User Interface ==
+In OTR program, first-tier options are following 
+ * protocol, debuglog
+"protocol" must be parsed correctly before other arguements relating to receiving functions could be understood. "debuglog" is used only for turning on the local logging of measurements. Because first-tier options are pivotal and governing 2nd-tier options in the program, run-time changes for them are impossible.
+
+Correspondingly, three fucntions are used in parsing options:
+ * parseOptionsPhase1
+ * parseOptionsPhase2
+ * parseRuntimeOptions
+
+''parseOptionsPhase1'' is used to set values for variable corresponding to first-tier arguments
+Because Gate is a virtual base class, a certain type of Gate object will be created based on ''prootcol_name''  variable.
+Second-tier options are parsed by ''parseOptionsPhase2''. Certain properties of newly created Gate object will be set.
+Finally, ''parseRuntimeOptions'' will parse run-time user input to change a certain set of parameters.
+For initial shell user inputs, ''argc'' and ''argv'' are automatically provided by standard C. So, we pass them to POPT function directly.
+But for run-time user inputs, a special char* variable ''msg'' is taken as the parameter. The msg contain the setting for only one options and either in "--option <arg>" format or without leading hyphons.
+
+== Difference between OTG and OTR user interface design
+
+As can be seen, the deisng for OTG and OTR user interfaces are quite similar, but there are two major differnce:
+ * Gate does not need "generator" related options
+ * Gate does not support run-time pause and resume options.
+
+== Discussion ==
+
+A major shortcoming of current design is the "--help" option does not disclose the full scale of option structure. Only first-tier options are showed.