Orbit > OTG > Function Specifications > User Interface

Function Specification: User Interface Design

User Interface 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 configuration 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 command inputs can only change one parameter a time. (multiple changes at the same time might lead mutual conflicting)

Brief introduction about 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" function call will return a value. Different options return different values. This occurs repetitively until the value returns -1. So, In "case" of different 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 arguments 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 functions 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 virtual 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 hyphens.

OTR User Interface

In OTR program, first-tier options are following

• protocol, debuglog

"protocol" must be parsed correctly before other arguments 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 functions 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 protocol_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 design for OTG and OTR user interfaces are quite similar, but there are two major difference:

• 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.