The LyXServer

Introduction

The LyX server is a method implemented in LyX that will enable other programs to talk to LyX, invoke LyX commands, and retrieve information about the LyX internal state. This is only intended for advanced users, but they should find it useful.

(Edit Section ↓)

Starting the LyXServer

The LyX server works through the use of a pair of named pipes. These are usually located in your home directory and have the names ".lyxpipe.in" and ".lyxpipe.out". External programs write into .lyxpipe.in and read back data from .lyxpipe.out. The stem of the pipe names can be defined in the Edit->Preferences:Inputs:Paths dialog, for example "/home/myhome/.lyxpipe".

LyX will add the '.in' and '.out' to create the pipes. The above setting also has the effect of activating the LyX server. If one of the pipes already exists, LyX will assume that another LyX process is already running and will not start the server. To have several LyX processes with servers at the same time, you have to change the configuration between the start of the programs.

If you are developing a client program, you might find it useful to enable debugging information from the LyX server. Do this by starting LyX as

 lyx -dbg 8192.

Warning: if LyX crashes, it may not manage to remove the pipes; in this case you must remove them manually. If LyX starts and the pipes exist already, it will not start any server.

Other than this, there are a few points to consider:

Both server and clients must run on UNIX or OS/2 machines. Communications between LyX on UNIX and clients on OS/2 or vice versa is not possible right now.

On OS/2, only one client can connect to LyXServer at a time.

On OS/2, clients must open inpipe with O_WRONLY mode.

You can find a complete example client written in C in the source distribution as development/server_monitor.c.

There is a client written in python at Tools.PyClient

(Edit Section ↓)

Normal communication

To issue a LyX call, the client writes a line of ASCII text into the input pipe. This line has the following format:

 LYXCMD:clientname:function:argument

Here clientname is a name that the client can choose arbitrarily. Its only use is that LyX will echo it if it sends an answer - so a client can dispatch results from different requesters.

function is the function you want LyX to perform. It is the same as the commands you'd use in the minibuffer.

argument is an optional argument which is meaningful only to some functions (for instance "self-insert" which will insert the argument as text at the cursor position.)

The answer from LyX will arrive in the output pipe and be of the form

 INFO:clientname:function:data

where clientname and function are just echoed from the command request, while data is more or less useful information filled according to how the command execution worked out. Some commands will return information about the internal state of LyX, such as "font-state", while other will return an empty data-response. This means that the command execution went fine.

In case of errors, the response from LyX will have this form

 ERROR:clientname:function:error message

where the error message should contain an explanation of why the command failed.

(Edit Section ↓)

Examples:

echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in

echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in read a <~/.lyxpipe.out echo $a

(Edit Section ↓)

Notification

LyX can notify clients of events going on asynchronously. Currently it will only do this if the user binds a key sequence with the function "notify". The format of the string LyX sends is as follows:

 NOTIFY:key-sequence

where key-sequence is the printed representation of the key sequence that was actually typed by the user.

This mechanism can be used to extend LyX's command set and implement macros: bind some key sequence to "notify", start a client that listens on the out pipe, dispatches the command according to the sequence and starts a function that may use LyX calls and LyX requests to issue a command or a series of commands to LyX.

(Edit Section ↓)

The simple LyX Server Protocol

LyX implements a simple protocol that can be used for session management. All messages are of the form

 LYXSRV:clientname:protocol message

where protocol message can be "hello" or "bye". If "hello" is received from a client, LyX will report back to inform the client that it's listening to it's messages, while "bye" sent from LyX will inform clients that LyX is closing.

source: LYXDIR/doc/Customization.lyx Note: the LyXServer chapter is not present in the German translation :-(

(Edit Section ↓)

On Windows

The lyxserver does not work on Windows as it is implemented in a unix-specific way. See http://www.archivesat.com/Lyx_editor_developer_help/thread2372934.htm for a refrence.

Uncategorized