This sections describes how MicroEmacs '06 may be interfaced to external components through the Client-Server interface.
The Client-Server interface of MicroEmacs '06 provides a capability for other applications to inject commands into a running version of the editor, which are interpreted and executed. The interface is only available on multi-tasking operating systems such as UNIX and Microsoft Windows; it is not available on MS-DOS systems.
Within the following discussions, the Server is a running version of the MicroEmacs '06 editor; the client is the application (or shell script) that communicates a new command to the server.
The Client-Server interface may provide a bidirectional interface such that a client may submit a command to the server and may also retrieve a response to that command.
The Client-Server interface operates by making an external interface available which is continually monitored by the server. The external interface may be provided by a file, named pipe or socket (depending upon the platform) with a well know location in the file system. Typically two files are provided, an input file into which the client writes commands ($TEMP/me$MENAME.cmd); and an output file where responses to those commands my be read ($TEMP/me$MENAME.rsp).
Within MicroEmacs, the client server interface appears as a hidden ipipe-shell-command(2) buffer, with the name *server*. Commands are received through this buffer and responses are written back to the buffer.
Clients may write directly to the command through the use of explicit embedded code, or may use a me(1) invocation with the -m option. Commands to the client interface take the form "C:<client>:<command>".
me -m "C:<client>:ml-write \"Hello world\"
A new line character may be included in the string using \\n, if the message is not terminated with a new line then on is automatically added. The client-server interface is typically used to load a file, this may be performed as follows:-
me -m "C:<client>:find-file \"/path/foo.bar\""
The absolute path is specified in this type of transaction as the current working directory of the active MicroEmacs session is unknown. The -m option de-iconize's the existing editor session and bring it to the foreground.
Responses from client commands are written to the response file, responses take a similar form to client commands except they are prefixed by an R, i.e. "R:<client>:<data>".
As multiple clients may be utilizing the client-server mechanism then the <client> sting passed in the command is typically returned in the response to allow the client to identify it's own response (rather than any other clients. It is the clients responsibility that this string is unique in order that it may be differentiated.
The returned <data> format is undefined and would be generated by a macro command used to handle the client command; sufficient to say that the data should exist on a single line.
On the server side, the Client-Server interface is managed like an ipipe-shell-command(2) using the hidden buffer *server* (as previously mentioned).
The client server interface is typically initialized within the me.emf initialization file, whereby the ipipe input handler is bound to the client pipe buffer and the buffer is hidden, so it is not available when the buffers are swapped. (Note that the client buffer may be explicitly interrogated using find-buffer *server*). The client handler is installed as follows:-
; Setup the Client Server !if &band $system 0x20000 define-macro-file meserver server-input find-buffer "*server*" set-variable :last-line 2 set-variable :client-list ":" set-variable $buffer-ipipe server-input beginning-of-buffer goto-alpha-mark "I" -1 find-buffer "*server*" !endif
This binds a MicroEmacs macro called server-input to handle the client commands as they arrive on the input, an alpha-mark is used to record the processed position at the end of the buffer. The pipe handler itself decodes the client request and executes it. The default handler supplied with MicroEmacs '06 is defined within the macro file meserver.emf
Responses to the client are inserted into the response file by writing directly into the ipipe buffer (*server*) using the ipipe-write(2) command. It is the calling macros responsibility to ensure that the response string adheres to the format outlined above in the previous sections.
It is not possible to kill the *server* buffer, and ipipe-kill(2) is ignored within the context of the buffer.
meserver.emf - Default Client-Server ipipe handler.
$TEMP/me$MENAME.cmd - Command file.
$TEMP/me$MENAME.rsp - Response file.
The first MicroEmacs '06 session that executes becomes the editor server, additional editor sessions that are executed do not become server processes. In the event that the server editor is terminated, any other sessions do not take over the role of server. Subsequently issuing a client command may fail, or invoke a new editor session which adopts the role of server.
Copyright (c) 1998-2006 JASSPA
Last Modified: 2006/08/21
Generated On: 2006/10/07