CallWeaver CLI utility - Specification

Document version: 1.0

Author: Benjamin Kowarsch

Copyright (c) 2006 Sunrise Telephone Systems Ltd., Tokyo, Japan

Permission is hereby granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, GFDL Version 1.2.

This Document is provided "as is" without any warranty of any kind.


1) Objective

The objective of this subproject is to remove the embedded command line
interface (CLI) from the CallWeaver server and to provide a replacement facility
in form of a standalone command line utility that acts as a client front-end.


2) Command line options

The CallWeaver CLI utility shall provide the following command line options:

-h and --help,  to print a brief online help

-v and --version,  to print the utility's version number

-c and --command,  to execute a single command and exit

-i and --interactive,  to invoke the utility in interactive mode

The default behaviour to exhibit when the utility is called without any
arguments shall be determined by a setting in the utility's property list
configuration file. If no configuration file is present and the utility is
called without any arguments, the help option shall be the default.


3) Configuration file settings

The CallWeaver CLI utility shall have its own configuration file which shall be
in property list format. The utility must not ever use Windows INI format or
the Windows derived Asterisk INI format for its configuration.

The utility shall read the following settings from its configuration file:

o  default mode,  mode to use when the utility is called without arguments

o  server socket,  full path to the CallWeaver server's UNIX domain socket

o  inactivity timeout,  duration of inactivity after which to disconnect

o  timestamp flag,  whether or not to print output with time stamps

o  prompt,  CLI prompt to display when in interactive mode

An example property list configuration is shown below:

CLIconfig = {
   DefaultMode = interactive;  /* interactive or command */
   ServerSocket = "/foo/bar/baz/opbxctl";
   InactivityTimeout = 0;
   PrintTimestamps = yes;
   Prompt = "OPBX>";
};


4) Startup sequence

The CallWeaver CLI utility shall use the following startup sequence when it is
launched ...

First it shall evaluate any command line arguments, then proceed as follows:

o  when invoked with the help option it shall print a brief online help,
   then exit.

o  when invoked with the version option it shall print the name of the
   utility followed by its version number, then exit.

o  when invoked with the single command option it shall read its configuration
   file to obtain the path to the server socket, connect to the server and
   request a list of loaded modules and their property lists. It shall then
   read the list and property lists to obtain the syntax of the command
   provided in the argument string. It shall then proceed to evaluate the
   command accordingly and submit the command if it is valid. Finally it
   shall read and print the server's response, then exit.

o  when invoked with the interactive mode option, it shall print the name and
   version of the utility, followed by the copyright and license notice. It
   shall then proceed to read its configuration file to obtain and apply the
   settings stored therein. It shall then connect to the server and request
   a list of loaded modules and their property lists. It shall then read the
   list of loaded modules and all property lists in order to obtain the
   syntax and online help of all available commands. Finally it shall print
   a CLI prompt and notify the user that it is ready for user input.

o  when invoked without any command line arguments, it shall read its
   configuration file to obtain the default mode setting, then proceed
   accordingly. If the default mode cannot be obtained, it shall proceed
   as if it had been invoked with the help option.


5) Obtaining information about command syntax and help

The CallWeaver CLI utility shall obtain information about loaded modules, their
commands, syntax and help by sending a request to the server which will
respond with a path to a loaded modules cache which contains the paths
to property lists describing the command syntax and help, one for each
loaded module. The CLI utility shall then read the loeaded module cache
and the property lists for all loaded modules and thereby obtain this
information directly. The server will only provide the location, but
not the information itself.

The CallWeaver CLI utility shall update the module cache whenever it receives
an update notification from the server. The server will provide an update
notification to each connected client whenever a reload has been executed.

/// TO DO: property list format for module command syntax and help

// END OF FILE