Next Previous Contents

1. Description of the protocol

The protocol is very simple. One command per line is sent. The commands specify fields, labels and some presentation constraints.

1.1 ASCII based, line oriented

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.

Argument quoting

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"
        

1.2 Commands expressed numerically

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.

1.3 Support for older front-end version

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.

alive

The front-end supports the Alive primitive.

gauge

The front-end has a gauge widget.

context

The front-end supports the Setcontext primitive.

html

The front-end can display HTML help.

listen

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

modal

The front-end can only deal with one dialog at a time (potentially a text base front-end).

nogfx

No icon should be sent. The front-end either does not support it or the user which to limit the amount of data transfered.

reconfdia

The front-end accept a redefinition of an existing dialog.

setval

The front-end supports the Setval primitive.

slider

The front-end has a slider widget.

treemenu

The front-end has a treemenu widget.

1.4 How to try the protocol

It is possible to run some sample of the protocol and see the GUI front end in action without using Linuxconf itself.

The remadmin script

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.

Using the wxXt version

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.

Using the Java version

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.

1.5 How to spy the protocol

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):

        make guispy
        

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
        

1.6 An example: form.simple

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
        


Next Previous Contents