Client-Server(2)

CLIENT-SERVER

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.

DESCRIPTION

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.

Client Commands

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

<client>


<client> is an identification string that may be used to identify the client, this information may be used when the command is handled to interpret the command if some special client specific action is required.

<command>


The <command> is an editor command (or macro) of the given name with any arguments. Standard command escape sequences must be adhered to. i.e. to write "Hello World" on the message line then a client may issue the 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.

Client Responses

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.

Server Side

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 enabled from the user-setup(3) interface, the user setting of the interface is confirmed by checking bit 0x20000 of the $system(5) variable.

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.

NOTES

It is not possible to kill the *server* buffer, and ipipe-kill(2) is ignored within the context of the buffer.

FILES

meserver.emf - Default Client-Server ipipe handler.
$TEMP/me$MENAME.cmd - Command file.
$TEMP/me$MENAME.rsp - Response file.

BUGS

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.

SEE ALSO

me(1), ipipe-shell-command(2)

Copyright (c) 1998-2006 JASSPA
Last Modified: 2006/08/21
Generated On: 2006/10/07