The protocol is very simple. One command per line is sent. The commands specify fields, labels and some presentation constraints.
The protocol is completely text based. No binary stuff. Each commands is sent on a single line. One command per line. The commands use a prefix format:
command_name arg1 arg2 ... $name1=val name2=val
The argument are positional. Optional arguments (and generally seldom used) are passed with their name. We could have used named parameter all the time, but this create some overhead to the protocol. The first argument starting with a dollar sign indicates the start of the named parameter section. Further argument do not need this dollar sign.
If an argument contains either white characters or starts with a double quote character, it must be enclosed in double quote. Any quote in the argument is escaped using a backslash character. Any backslash is also escaped. Here are few examples.
Argument Sent -------- ---------- onearg onearg one arg "one arg" "onearg "\"onearg" one\arg one\arg one"arg one"arg one \ arg "one \\ arg" $hello "$hello"
Command may be sent as name or as number. All the command names are defined in the file diajava/proto.lst. From this file, other files are generated. One is diajava/proto.h. Instead of sending names, Linuxconf choose to send numbers (in text form). This make the protocol tiner. It is expect that the GUI front-end will often talk to Linuxconf over a slow Internet link, so saving few bytes here may be worth it.
The current implementation of remadmin (java and wxXt) support both numerical command and text.
When the application (Linuxconf) connects to front-end, this one immediatly send a control line telling which features it supports. This exist so newer application can run with older front-end. This also exist so front-end with various capabilities may co-exist. Ultimatly the feature list may be controlled by the user. The line looks like:
prefer feature1 feature2 ...
Here are the feature currently understood.
The front-end supports the Alive primitive.
The front-end has a gauge widget.
The front-end supports the Setcontext primitive.
The front-end can display HTML help.
The front-end can handle the Listen directive. It control the availability of a form/dialog. A form may or may not react to user input. It may be presented differently to show its state (gray out).
The front-end can only deal with one dialog at a time (potentially a text base front-end).
No icon should be sent. The front-end either does not support it or the user which to limit the amount of data transfered.
The front-end accept a redefinition of an existing dialog.
The front-end supports the Setval primitive.
The front-end has a slider widget.
The front-end has a treemenu widget.
It is possible to run some sample of the protocol and see the GUI front end in action without using Linuxconf itself.
Linuxconf delivers a script called /bin/remadmin. This simple script picks the more appropriate GUI server. If none is available, it return a message to linuxconf, and linuxconf switch to its native ncurses user interface.
If you develop a new GUI server, check out this script and modify it so your server will be called.
The wxxt-linuxconf utility is delivered with Linuxconf, so you can use it to do some test. Currently, this is the only operational version of the front end, so this is the reference. Just do this
(cat a_test_file; cat) | wxxt-linuxconf --pipe
wxxt-linuxconf exits as soon as the sending process terminates. This is why you need the trickery with the parentheses. The first "cat" command send the test file and the second one maintain the pipe open until you control-C out of this.
If you have Java installed on your station, you can do various test with the GUI server to check out its behavior. Do this
(cd /usr/lib/linuxconf/java; java mformscript) <a_test_file
This will process the test file (which contain GUI commands) and pops up a dialog done with these commands.
The various example in this document are located in the diajava/examples directory of the Linuxconf sources. In this directory you will find various files form.* which contains different tests. You will also find a script show.sh used to display those tests. Simply run show.sh like this
cd diajava/examples ./show.sh form.simple
You can ctrl-C out anytime.
It is possible to setup a spy which will log all communications between Linuxconf and the GUI frontend. The program guispy in the diajava/ directory has been created just for that. Compile it by doing (It is not part of the binary distribution of Linuxconf):
The run the following command (note the absolute paths used for the commands)
remadmin --exec ./guispy /tmp/in.log /tmp/out.log \ /bin/linuxconf --guiproto
Two text files will be produced: /tmp/in.log and /tmp/out.log. /tmp/out.log contains the protocol requests sent by Linuxconf. This file is larger. /tmp/in.log contains the answers sent by remadmin.
Note that you can play back a session by doing:
(cat /tmp/out.log; cat) | remadmin --pipe
Here is an example of a small dialog:
MainForm basic "Basic menu" Label "Your name" String S1 15 Newline Label Telephone String S2 15 Newline Label Status Radio R1 1 0 single Radio R1 2 0 Married Newline Button B1 Accept Button B2 Cancel End