alx/mu4e
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mu-server: update documentation

Browse Source
This commit is contained in:
Dirk-Jan C. Binnema
2020-01-19 21:38:05 +02:00
parent d2ec85f01c
commit 232f370936
2 changed files with 69 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
man/mu-server.1
View File

@ -1,4 +1,4 @@
.TH MU-SERVER 1 "September 2012" "User Manuals" .TH MU-SERVER 1 "January 2020" "User Manuals"
.SH NAME .SH NAME
@ -10,27 +10,28 @@ mu server \- the mu backend for the mu4e e-mail client
.SH DESCRIPTION .SH DESCRIPTION
\fBmu server\fR starts a simple shell in which one can query and manipulate \fBmu server\fR starts a simple shell in which one can query and manipulate the
the mu database. The output of the commands is terms of Lisp symbolic mu database. The output uses s-expressiong. \fBmu server\fR is not meant for use
expressions (s-exps). \fBmu server\fR is not meant for use by humans; instead, by humans, except for debugging purposes. Instead, it is designed specifically
it is designed specifically for the \fBmu4e\fR e-mail client. for the \fBmu4e\fR e-mail client.
In this man-page, we document the commands \fBmu server\fR accepts, as well as In this man-page, we document the commands \fBmu server\fR accepts, as well as
their responses. In general, the commands sent to the server are of the form their responses. In general, the commands sent to the server are s-expressions
of the form:
.nf .nf
cmd:<command> [<parameters>]* (<command-name> :param1 value1 :param2 value2)
.fi .fi
where each of the parameters is prefixed by their name and a colon. For For example, to view a certain message, the command would be:
example, to view a certain message, the command would be:
.nf .nf
cmd:view docid:12345 (view :docid 12345)
.fi .fi
Parameters can be sent in any order, and parameters not used by a certain Parameters can be sent in any order; they must be of the correct type though.
command are simply ignored. See \fBlib/utils/mu-sexp-parser.hh\fR and \fBlib/utils/mu-sexp-parser.hh\fR in
source-tree for the details.
.SH OUTPUT FORMAT .SH OUTPUT FORMAT
@ -50,223 +51,8 @@ By prefixing the expression with its length, it can be processed more
efficiently. The \\376 and \\377 were chosen since they never occur in valid efficiently. The \\376 and \\377 were chosen since they never occur in valid
UTF-8 (in which the s-expressions are encoded). UTF-8 (in which the s-expressions are encoded).
.SH COMMAND AND RESPONSE .sh COMMANDS
.TP
.B add
Using the \fBadd\fR command, we can add a message to the database.
.nf
-> cmd:add path:<path> maildir:<maildir>
<- (:info add :path <path> :docid <docid>)
.fi
.TP
.B compose
Using the \fBcompose\fR command, we get the (original) message, and tell what
to do with it. The user-interface is then expected to pre-process the message,
e.g. set the subject, sender and recipient for a reply message.
Messages of type 'new' don't use the docid: parameter, the other ones do.
.nf
-> cmd:compose type:<reply|forward|edit|new> [docid:<docid>]
<- (:compose <reply|forward|edit|new> :original <s-exp> :include (<list-of-attachments))
.fi
The <list-of-attachments> is an s-expression describing the attachments to
include in the message; this currently only applies to message we are
forwarding. This s-expression looks like:
.nf
(:file-name <filename> :mime-type <mime-type> :disposition <disposition>)
.fi
.TP
.B contacts
Using the \fBcompose\fR command, we can retrieve an s-expression with all known
contacts (name + e-mail address). For the details, see \fBmu-cfind(1)\fR.
.nf
-> cmd:contacts [personal:true|false] [after:<time_t>]
<- (:contacts ((:name abc :mail foo@example.com ...) ...)
.fi
.TP
.B extract
Using the \fBextract\fR command we can save and open attachments.
.nf
-> cmd:extract action:<save|open|temp> index:<index> [path:<path>] [what:<what> [param:<param>]]
.fi
If the action is 'save', the path argument is required; the attachment will
be saved, and a message
.nf
<- (:info save :message "... has been saved")
.fi
is sent.
If the action is 'open', the attachment will saved to a temporary file, after
which it will be opened with the default handler for this kind of file (see
\fBmu-extract\fR(1)), and a message
.nf
<- (:info open :message "... has been opened")
.fi
is sent.
If the action is 'temp', the arguments 'what' is required. The attachment will
saved to a temporary file, and the following message is sent:
.nf
<- (:temp :what <what> :param <param :docid 12345)
.fi
The front-end can then take action on the temp file, based on what :what and
:param contain. \fBmu4e\fR uses this mechanism e.g. for piping an attachment
to a shell command.
.TP
.B find
Using the \fBfind\fR command we can search for messages.
.nf
-> cmd:find query:"<query>" [threads:true|false] [sortfield:<sortfield>]
[reverse:true|false] [maxnum:<maxnum>]
.fi
The \fBquery\fR-parameter provides the search query; the
\fBthreads\fR-parameter determines whether the results will be returned in
threaded fashion or not; the \fBsortfield\fR-parameter (a string, "to",
"from", "subject", "date", "size", "prio") sets the search field, the
\fBreverse\fR-parameter, if true, set the sorting order Z->A and, finally, the
\fBmaxnum\fR-parameter limits the number of results to return (<= 0
means 'unlimited').
First, this will return an 'erase'-sexp, to clear the buffer from possible
results from a previous query.
.nf
<- (:erase t)
.fi
This will return a series of 0 up to <maxnum> s-expression corresponding to
each message found (if there's no maxnum, all results will be returned). The
information message s-exps this function returns do not contain the message
body; the \fBview\fR command is for that.
.nf
<- (...)
.fi
and finally, we receive:
.nf
<- (:found <number-of-matches>)
.fi
.TP
.B guile
The \fBguile\fR command is reserved for future use.
.TP
.B index
Using the \fBindex\fR command, we can (re)index the database, similar to what
\fBmu find\fR does. The \fBmy-addresses\fR parameter (optionally)
registers 'my' email addresses; see the documentation for
\fBmu_store_set_my_addresses\fR.
.nf
-> cmd:index path:<path> [my-addresses:<comma-separated-list-of-email-addresses>]
.fi
As a response, it will send (for each 1000 messages):
.nf
(:info index :status running :processed <processed> :updated <updated>)
.fi
and finally:
.nf
(:info index :status complete :processed <processed :updated <updated>
:cleaned-up <cleaned-up>)
.fi
.TP
.B mkdir
Using the \fBmkdir\fR command, we can create a new maildir.
.nf
-> cmd:mkdir path:<path>
<- (:info mkdir :message "<maildir> has been created")
.fi
.TP
.B move
Using the \fBmove\fR command, we can move messages to another maildir or
change its flags (which ultimately means it is being move to a different
filename), and update the database correspondingly. The function returns an
s-exp describing the updated message, so that it can be updated in the user
interface.
.nf
-> cmd:move docid:<docid>|msgid:<msgid> [maildir:<maildir>] [flags:<flags>]
<- (:update <s-exp> :move t)
.fi
One of docid and msgid must be specified to identify the message. At least one
of maildir and flags must be specified.
.TP
.B ping
The \fBping\fR command provokes a \fBpong\fR response. It is used for the initial
handshake between \fBmu4e\fR and \fBmu server\fR.
.nf
-> cmd:ping
<- (:pong "mu" :version <version> :doccount <doccount>)
.fi
.TP
.B remove
Using the \fBremove\fR command, we can remove the message from disk, and
update the database accordingly.
.nf
-> cmd:remove docid:<docid>
<- (:remove <docid>)
.fi
.TP
.B view
Using the \fBview\fR command, we can retrieve all information (including the
body) of a particular e-mail message.
If the optional parameter \fBextract-images\fR is \fBtrue\fR, extract images
to temp files, and include links to them in the returned s-exp.
If the optional parameter \fBuse-agent\fR is \fBtrue\fR, try to use
\fBgpg-agent\fR when verifying PGP/GPG message parts.
If the optional parameter \fBauto-retrieve-key\fR is \fBtrue\fR, attempt to
retrieve public keys online automatically.
.nf
-> cmd:view docid:<docid>|msgid:<msgid> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
<- (:view <s-exp>)
.fi
or, alternatively:
.nf
-> cmd:view path:<path-to-msg> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
<- (:view <s-exp>)
.fi
.SH AUTHOR .SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

101
mu4e/mu4e.texi
View File

@ -4568,22 +4568,23 @@ them. @t{mu} can run in a special @t{server}-mode, where it provides services
@node mu server @node mu server
@section @t{mu server} @section @t{mu server}
@t{mu4e} is based on the @t{mu} e-mail searching/indexer. The latter is a @t{mu4e} is based on the @t{mu} e-mail searching/indexer. The latter
C-program; there are different ways to communicate with a client that is is a C++-program; there are different ways to communicate with a
emacs-based. client that is emacs-based.
One way to implement this, would be to call the @t{mu} command-line tool with One way to implement this, would be to call the @t{mu} command-line
some parameters and then parse the output. In fact, that was the first tool with some parameters and then parse the output. In fact, that was
approach --- @t{mu4e} would invoke e.g., @t{mu find} and process the output in the first approach --- @t{mu4e} would invoke e.g., @t{mu find} and
@command{emacs}. process the output in @command{emacs}.
However, with this approach, we need to load the entire e-mail @emph{Xapian} However, with this approach, we need to load the entire e-mail
database (in which the message is stored) for each invocation. Wouldn't it be @emph{Xapian} database (in which the message is stored) for each
nicer to keep a running @t{mu} instance around? Indeed, it would --- and thus, invocation. Wouldn't it be nicer to keep a running @t{mu} instance
the @t{mu server} sub-command was born. Running @t{mu server} starts a simple around? Indeed, it would --- and thus, the @t{mu server} sub-command
shell, in which you can give commands to @command{mu}, which then spits out was born. Running @t{mu server} starts a simple shell, in which you
the results/errors. @command{mu server} is not meant for humans, but it can be can give commands to @command{mu}, which then spits out the
used manually, which is great for debugging. results/errors. @command{mu server} is not meant for humans, but it
can be used manually, which is great for debugging.
@node Reading from the server @node Reading from the server
@section Reading from the server @section Reading from the server
@ -4610,10 +4611,11 @@ invoked whenever the process has some data for us. Something like:
(set-process-sentinel proc 'my-process-sentinel)) (set-process-sentinel proc 'my-process-sentinel))
@end lisp @end lisp
Note, the process sentinel is invoked when the process is terminated --- so Note, the process sentinel is invoked when the process is terminated
there you can clean things up. The function @code{my-process-filter} is a --- so there you can clean things up. The function
user-defined function that takes the process and the chunk of output as @code{my-process-filter} is a user-defined function that takes the
arguments; in @t{mu4e} it looks something like (pseudo-lisp): process and the chunk of output as arguments; in @t{mu4e} it looks
something like (pseudo-lisp):
@lisp @lisp
(defun my-process-filter (proc str) (defun my-process-filter (proc str)
@ -4625,16 +4627,19 @@ arguments; in @t{mu4e} it looks something like (pseudo-lisp):
<evaluate-expression>)) <evaluate-expression>))
@end lisp @end lisp
@code{<evaluate-expression>} de-multiplexes the s-expression we got. For @code{<evaluate-expression>} de-multiplexes the s-expression we got.
example, if the s-expression looks like an e-mail message header, it is For example, if the s-expression looks like an e-mail message header,
processed by the header-handling function, which appends it to the header it is processed by the header-handling function, which appends it to
list. If the s-expression looks like an error message, it is reported to the the header list. If the s-expression looks like an error message, it
user. And so on. is reported to the user. And so on.
The language between frontend and backend is documented in the @t{mu-server} The language between frontend and backend is documented partly in the
man-page. @t{mu4e} can log these communications; you can use @kbd{M-x @t{mu-server} man-page and more completely in the output of @t{mu
mu4e-toggle-logging} to turn logging on and off, and you can view the log server --commands}.
using @kbd{M-x mu4e-show-log} (@key{$}).
@t{mu4e} can log these communications; you can use @kbd{M-x
mu4e-toggle-logging} to turn logging on and off, and you can view the
log using @kbd{M-x mu4e-show-log} (@key{$}).
@node The message s-expression @node The message s-expression
@section The message s-expression @section The message s-expression
@ -4680,8 +4685,9 @@ Some notes on the format:
where @t{name} can be @t{nil}. where @t{name} can be @t{nil}.
@item The date is in format @command{emacs} uses (for example in @item The date is in format @command{emacs} uses (for example in
@code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits @code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits
available for the actual number; the other bits are use by @command{emacs} for available for the actual number; the other bits are use by
internal purposes. Therefore, we need to split @t{time_t} in two numbers.} @command{emacs} for internal purposes. Therefore, we need to split
@t{time_t} in two numbers.}
@item Attachments are a list of elements with fields @t{:index} (the number of @item Attachments are a list of elements with fields @t{:index} (the number of
the MIME-part), @t{:name} (the file name, if any), @t{:mime-type} (the the MIME-part), @t{:name} (the file name, if any), @t{:mime-type} (the
MIME-type, if any) and @t{:size} (the size in bytes, if any). MIME-type, if any) and @t{:size} (the size in bytes, if any).
@ -4692,24 +4698,26 @@ MIME-type, if any) and @t{:size} (the size in bytes, if any).
@subsection Example: ping-pong @subsection Example: ping-pong
As an example of the communication between @t{mu4e} and @command{mu}, let's As an example of the communication between @t{mu4e} and @command{mu},
look at the @t{ping-pong}-sequence. When @t{mu4e} starts, it sends a command let's look at the @t{ping-pong}-sequence. When @t{mu4e} starts, it
@t{ping} to the @t{mu server} backend, to learn about its version. @t{mu sends a command @t{ping} to the @t{mu server} backend, to learn about
server} then responds with a @t{pong} s-expression to provide this information its version. @t{mu server} then responds with a @t{pong} s-expression
(this is implemented in @file{mu-cmd-server.c}). to provide this information (this is implemented in
@file{mu-cmd-server.c}).
We start this sequence when @t{mu4e} is invoked (when the program is We start this sequence when @t{mu4e} is invoked (when the program is
started). It calls @t{mu4e-proc-ping}, and registers a (lambda) function for started). It calls @t{mu4e-proc-ping}, and registers a (lambda) function for
@t{mu4e-proc-pong-func}, to handle the response. @t{mu4e-proc-pong-func}, to handle the response.
@verbatim @verbatim
-> cmd:ping -> (ping)
<- (pong "mu" :version "x.x.x" :doccount 10000) <-<prefix>(:pong "mu" :props (:version "x.x.x" :doccount 78545))
@end verbatim @end verbatim
When we receive such a @t{pong} (in @file{mu4e-proc.el}), the lambda function When we receive such a @t{pong} (in @file{mu4e-proc.el}), the lambda
we registered is called, and it compares the version we got from the @t{pong} function we registered is called, and it compares the version we got
with the version we expected, and raises an error if they differ. from the @t{pong} with the version we expected, and raises an error if
they differ.
@node Debugging @node Debugging
@appendix Debugging @appendix Debugging
@ -4717,14 +4725,15 @@ with the version we expected, and raises an error if they differ.
As explained in @ref{How it works}, @t{mu4e} communicates with its backend As explained in @ref{How it works}, @t{mu4e} communicates with its backend
(@t{mu server}) by sending commands and receiving responses (s-expressions). (@t{mu server}) by sending commands and receiving responses (s-expressions).
For debugging purposes, it can be very useful to see this data. For this For debugging purposes, it can be very useful to see this data. For
reason, @t{mu4e} can log all these messages. Note that the `protocol' is this reason, @t{mu4e} can log all these messages. Note that the
documented to some extent in the @t{mu-server} manpage. `protocol' is documented to some extent in the @t{mu-server} manpage.
You can enable (and disable) logging with @kbd{M-x mu4e-toggle-logging}. The You can enable (and disable) logging with @kbd{M-x
log-buffer is called @t{*mu4e-log*}, and in the @ref{Main view}, @ref{Headers mu4e-toggle-logging}. The log-buffer is called @t{*mu4e-log*}, and in
view} and @ref{Message view}, there's a keybinding @key{$} that takes you the @ref{Main view}, @ref{Headers view} and @ref{Message view},
there. You can quit it by pressing @key{q}. there's a keybinding @key{$} that takes you there. You can quit it by
pressing @key{q}.
Logging can be a bit resource-intensive, so you may not want to leave Logging can be a bit resource-intensive, so you may not want to leave
it on all the time. By default, the log only maintains the most recent it on all the time. By default, the log only maintains the most recent