• View
• Edit
• Upload
• History
• Print

LyXServer

The LyXServer communicates with LyX via named pipes.

1.  About the LyXServer

The LyXServer is a method implemented in LyX that enables other programs to communicate with LyX, invoke LyX commands, and retrieve information about LyX's internal state. Why would you want to do that? Well for example when citing you might want to switch to your reference management software (such as JabRef) and check you have the right reference, or indeed all the relevant references, and then push them to the insertion point in LyX. Another example would be opening a file in an already running instance of LyX (see this page).

The following description is only intended for advanced users, but they might find it useful.

LyXServer

2.  Starting the LyXServer

2.1  UNIX

The LyXServer uses 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 Edit→Preferences→Inputs→Paths, for example "~/.lyxpipe".

According to this thread on the ubuntu forums JabRef expects the pipe to be at ~/.lyx/lyxpipe. (Tools→Reconfigure and restart LyX). This works for me and I can switch to JabRef and push references to my current insertion point in my LyX document.

LyX adds the '.in' and '.out' suffixes while creating the pipes. The above setting also has the effect of activating the LyXServer. 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 starts of the programs.

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

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 the LyXServer at a time.
• On OS/2, clients must open inpipe with O_WRONLY mode.

You can find some complete example clients written in C, tcl and perl in the source distribution at development/lyxserver/.

There is also a client written in python at Tools.PyClient

2.2  On Windows

As of LyX 1.6.5, the lyxserver also works on Windows. See the Additional Features manual, chapter 4, for further details. On LyX 1.6.4 and earlier versions, the lyxserver does not work on Windows (except Cygwin), as it was implemented in a UNIX-specific way. Lyxserver does not use normal files but uses Windows' notation (\\.\pipe\lyxserver ) for named pipes. More information can be found here

To set up the LyXServer, set the named pipe in Menu→Tools→Preferences→Paths→LyxServer path to

LyX adds the '.in' and '.out' suffixes while creating the pipes when LyX is launched. The above setting also has the effect of activating the LyXServer. 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 starts of the programs.

Client applications, such as JabRef, can be used to push citations to LyX via the LyXServer. In Options→Preferences→External Program→Setting for insert selected citations into Lyx/Kile, there's a widget to configure the lyxserver. Input the string

LyXOnWindows, JabRef, BibTeX

3.  Details for Protocol Implementation in Applications

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

3.2  Examples:

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

echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in

read a <~/.lyxpipe.out

echo $a

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

3.4  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