% manual.tex
% ----------
% Copyright : (c) 2011, Jeremie Dimino <jeremie@dimino.org>
% Licence   : BSD3
%
% This file is a part of obus, an ocaml implementation of D-Bus.

\documentclass{article}
\usepackage{fullpage}
\usepackage[utf8]{inputenc}
\usepackage{url}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{xspace}

%% +------------------------------------------------------------------+
%% | Configuration                                                    |
%% +------------------------------------------------------------------+

\hypersetup{%
  a4paper=true,
  pdfstartview=FitH,
  colorlinks=false,
  pdfborder=0 0 0,
  pdftitle = {OBus user manual},
  pdfauthor = {Jérémie Dimino},
  pdfkeywords = {OCaml, D-Bus}
}

\lstset{
  language=[Objective]Caml,
  extendedchars,
  showspaces=false,
  showstringspaces=false,
  showtabs=false,
  basicstyle=\ttfamily,
  frame=l,
  framerule=1.5mm,
  xleftmargin=6mm,
  framesep=4mm,
  rulecolor=\color{lightgray},
  emph={lwt,for\_lwt,try\_lwt,raise\_lwt},
  emphstyle=\color[rgb]{0.627451, 0.125490, 0.941176},
  moredelim=*[s][\itshape]{(*}{*)},
  moredelim=[is][\textcolor{darkgray}]{§}{§},
  escapechar=°,
  keywordstyle=\color[rgb]{0.627451, 0.125490, 0.941176},
  stringstyle=\color[rgb]{0.545098, 0.278431, 0.364706},
  commentstyle=\color[rgb]{0.698039, 0.133333, 0.133333},
  numberstyle=\color[rgb]{0.372549, 0.619608, 0.627451}
}

%% +-----------------------------------------------------------------+
%% | Aliases                                                         |
%% +-----------------------------------------------------------------+

\newcommand{\obus}{\texttt{OBus}\xspace}
\newcommand{\dbus}{\texttt{D-Bus}\xspace}

%% +-----------------------------------------------------------------+
%% | Headers                                                         |
%% +-----------------------------------------------------------------+

\title{OBus user manual}
\author{Jérémie Dimino}

\begin{document}

\maketitle

%% +-----------------------------------------------------------------+
%% | Abstract                                                        |
%% +-----------------------------------------------------------------+

\begin{abstract}

  \dbus is an inter-processes communication protocol, or IPC for
  short, which has recently become a standard on desktop oriented
  computers. It is now possible to talk to a lot application using
  \dbus. Moreover, it has many bindings/implementations for differents
  languages, which make it easily accessible. \obus is a pure OCaml
  implementation of this protocol. What makes it different from other
  bindings/implementations is that it is the only one using
  cooperative threads, which make it very simple to fully exploit the
  asynchronous nature of D-Bus.

  \textbf{Note:} it is advised to have some knowledge about the
  \texttt{Lwt} library before reading this manual.
\end{abstract}

%% +-----------------------------------------------------------------+
%% | Table of contents                                               |
%% +-----------------------------------------------------------------+

\setcounter{tocdepth}{2}
\tableofcontents

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Introduction}

\subsection{Overview of \obus}

\subsubsection{Packages}

The main packages of the \obus distribution is the \obus package,
available via findlib. It contains the core library. Moveover, \obus
although provides packages for using a bunch of services of the
Freedesktop project:

\begin{itemize}
\item \texttt{obus.hal}
\item \texttt{obus.notification}
\item \texttt{obus.network-manager}
\item \texttt{obus.policykit}
\item \texttt{obus.udisks}
\item \texttt{obus.upower}
\end{itemize}

The use of these packages is straightforward and you need to know
almost nothing about \dbus or \obus. For example, here is a program
which open a popup notification:

\begin{lstlisting}
open Notification

lwt () =
  lwt id = Notification.notify ~summary:"Hello, world!" () in
  return ()
\end{lstlisting}

Lastly \obus also provides a syntax extension (package
\texttt{obus.syntax}) and a parser/printer for the IDL language
(package \texttt{obus.idl}).

\subsubsection{Modules}

\obus contains about 30 public modules. But do not be scared, most of
the time you will need a very small subset of them. These modules can
be divided in two categories:

\begin{itemize}
\item{the high-level API}
\item{the low-level API}
\end{itemize}

The low-level API is described in the section ~\ref{lowlevel-section}
of this manual. Note that you must have a good knowledge of \dbus to
use it.

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Quick start}

In this section we explain how to quickly uses a \dbus service using
\obus.

\begin{itemize}
\item The first step is to obtain the introspection of the
  service. Some applications put theses file into
  \texttt{/usr/share/dbus-1/interfaces/}. Otherwise you can get it by
  introspecting a running service, for example:

  \lstset{language=bash}
  \begin{lstlisting}
$ obus-introspect -rec org.foo.bar / > foo.xml
  \end{lstlisting}

  will recursivelly introspect the service named \texttt{org.foo.bar}
  and put all the interfaces it implements into \texttt{foo.xml}.

\item The second step is to turn this file into an ocaml module which
  contains the description of the interface:

  \lstset{language=bash}
  \begin{lstlisting}
$ obus-gen-interface foo.xml
  \end{lstlisting}

  This will create the two files \texttt{foo\_interfaces.ml} and
  \texttt{foo\_interfaces.ml}.

\item The final step is to turn the introspection file into a module
  for client-side use:

  \lstset{language=bash}
  \begin{lstlisting}
$ obus-gen-client foo.xml
  \end{lstlisting}

  This will produce the two files \texttt{foo\_client.mli} and
  \texttt{foo\_client.ml}. These two files can be edited, and must be
  compiled with the \texttt{lwt.syntax} syntax extension.
\end{itemize}

After that, you can use \texttt{Foo\_client} module to access the
service.  Methods are mapped to functions returning a \texttt{lwt}
thread, signals are mapped to values of type \texttt{OBus\_signal.t},
and properties to values of type \texttt{OBus\_property.t}. For
example:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
lwt () =
  (* Connect to the session bus *)
  lwt bus = OBus_bus.session () in

  (* Create a proxy for a remote object *)
  let proxy =
    OBus_proxy.make
      (OBus_peer.make bus "org.foo.bar")
      ["org"; "foo"; "bar"]
  in

  (* Call a method of the servivce *)
  lwt result = Foo_client.Org_foo_bar.plop proxy ... in

  (* Connect to a signal of the service *)
  lwt () =
    Lwt_react.E.notify (fun args -> ...)
    =|< OBus_signal.connect (Foo_client.Org_foo_bar.plip proxy)
  in

  (* Read the contents of a property *)
  lwt value = OBus_property.get (Foo_client.Org_foo_bar.plap proxy) in

  ...
\end{lstlisting}

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Basis}

In this section we will describe the minimum you must know to use
\obus and interfaces for \dbus services written with \obus (like the
ones provided in the \obus distribution: \texttt{obus.notification},
\texttt{obus.upower}, \dots).

\subsection{Connections and message buses}

A \emph{connection} is a way of exchanging messages with another
application speaking the \dbus protocol. Most of the time applications
use connection to a special application called a \emph{message bus}. A
message bus act as a router between several applications. On a desktop
computer, there are two well-known instances: the \emph{system}
message bus, and the user \emph{session} message bus.

The first one is unique given a computer, and use security
policies. The second is unique given a user session. Its goal is to
allow programs running in the session to talk to each other. \obus
offers two function for connecting to these message buses:
\texttt{OBus\_bus.session} and \texttt{OBus\_bus.system}.

The session bus exists for the life-time of a user session. It exits
when the session is closed, and any programs using it should exit to,
that is why \obus will exit the program when the connection to the
session bus is lost. However this behavior can be changed.

On the other hand the system bus can be restarted and program using it
may try to reopen the connection. System-wide application should
handle the lost of the connection with the system bus.

Here is a small example which connects the session bus and prints its
id:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
open Lwt

lwt () =
  (* Open a connection to the session message bus: *)
  lwt bus = OBus_bus.session () in

  (* Obtain its id: *)
  lwt id = OBus_bus.get_id bus in

  Lwt_io.printlf "The session bus id is %d." (OBus_uuid.to_string id)
\end{lstlisting}

\subsection{Names}

On a message bus, applications are referenced using names. There is a
special category of names called \emph{unique names}. Each time an
application connects to a bus, the bus give it a unique name. Unique
name are of the form \texttt{:1.42} and cannot be changed. You can
think of a unique name as an \emph{ip} (such as
\texttt{192.168.1.42}).

Once connected, the unique name can is returned by the function
\texttt{OBus\_bus.name}.  Here is an example of a program that prints
its unique name:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
open Lwt

lwt () =
  (* Connects to the session bus: *)
  lwt bus = OBus_bus.session () in

  (* Read our unique name: *)
  let name = OBus_bus.name bus in

  Lwt_io.printlf "My unique connection name is %s." name
\end{lstlisting}

Unique name are usefull to uniquelly identify an application. However
when you want to use a specific service you may prefer using a
well-known name such as \texttt{org.freedesktop.Notifications}. \dbus
allows applications to own as many non-unique names as they want. You
can think of a non-unique name as a \emph{dns} (such as
``obus.forge.ocamlcore.org'').

Names can be requested or resolved using functions of the
\texttt{OBus\_bus} module.

Here is an example:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
open Lwt

lwt () =
  lwt bus = OBus_bus.session () in

  lwt () =
    try_lwt
      (* Try to resolve a name, this may fail if nobody owns it: *)
      lwt owner = OBus_bus.get_name_owner bus "org.freedesktop.Notifications" in
      Lwt_io.printlf "The owner is %d."
    with OBus_bus.Name_has_no_owner msg ->
      Lwt_io.printlf "Cannot resolve the name: %s." msg
  in

  (* Request a name: *)
  OBus_bus.request_name bus "org.foo.bar" >>= function
    | `Primary_owner ->
        Lwt_io.printl "I own the name org.foo.bar!"
    | `In_queue ->
        Lwt_io.printl "Somebody else owns the name, i am in the queue."
    | `Exists ->
        Lwt_io.printl "Somebody else owns the name\
                       and does not want to loose it :(."
    | `Already_owner
        (* Cannot happen *)
        Lwt_io.printl "I already owns this name."
\end{lstlisting}

Note that the \texttt{OBus\_resolver} module offer a better way of
resolving names and monitoring name owners. See section
~\ref{name-tracking} for details.

\subsection{Peers}

A \emph{peer} represent an application accessible through a \dbus
connection.  To uniquelly identify a peer one needs a connection and a
name. The module \texttt{OBus\_peer} defines the type type of
peers. There are two requests that should be available on all peers:
\texttt{ping} and \texttt{get\_machine\_id}.  The first one just ping
the peer to see if it is alive, and the second returns the id of the
machine the peer is currently running on.

\subsection{Objects and proxies}

In order to export services, \dbus uses the concept of
\emph{objects}. An application may holds as many objects as it
wants. From the inside of the application, \dbus objects are generally
mapped to language native objects. From the outside, objects are
refered by \emph{object-paths}, which looks like
``\texttt{/org/freedesktop/DBus}''. You can think of an object path as
a pointer.

Objects may have members which are organized by interfaces (such as
``\texttt{org.freedesktop.DBus}'').  There are three types of members:

\begin{itemize}
\item Methods
\item Signals
\item Properties
\end{itemize}

Methods act like functions. Clients can call methods of
objects. Signals are spontaneous events that may occurs at any
time. Clients may register to these signals and then be notified when
a signal arrive. Properties act as variable, that can be read and/or
written and sometimes monitored.

In order to uniquelly identify an object, we need its path and the
peer that owns it. We call such a thing a \emph{proxy}. Proxies are
defined in the module \texttt{OBus\_proxy}.

Here is a simple example on how to call a method on a proxy (we will
explain latter what means the \texttt{C.seq...} things):

\lstset{language=[Objective]Caml}
\begin{lstlisting}
open Lwt
open OBus_value

lwt () =
  lwt bus = OBus_bus.session () in

  (* Create the peer: *)
  let peer = OBus_peer.make ~name:"org.freedesktop.DBus" ~connection:bus in

  (* Create the proxy: *)
  let proxy = OBus_proxy.make ~peer ~path:["org"; "freedesktop"; "DBus"] in

  (* Call a method: *)
  lwt id =
    OBus_proxy.call proxy
      ~interface:"org.freedesktop.DBus"
      ~member:"GetId"
      ~i_args:C.seq0
      ~o_args:(C.seq1 C.basic_string)
      ()
  in

  Lwt_io.printlf "The bus id is: %s" id
\end{lstlisting}

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Interaction between the OCaml world and the D-Bus world}

\subsection{Value mapping}

\dbus defines its own type system, which is used to serialize and
deserialize messages. These types are defined in the module
\texttt{OBus\_value.T} and \dbus values that are defined in the module
\texttt{OBus\_value.V}. When a message is received, its contents is
represented as a value of type \texttt{OBus\_value.V.sequence}.
Simillary, when a message is sent, it is first converted into this
format.

Manipulating boxed \dbus values is not very handy. To make the
interaction more transparent, \obus defines a set of type combinators
which allow to easilly switch between the \dbus representation and the
ocaml representation. These convertors are defined in the module
\texttt{OBus\_value.C}.

Here is an example of convertion (in the toplevel):

\lstset{language=[Objective]Caml}
\begin{lstlisting}
# open OBus_value;;

(* Make a D-Bus value from an ocaml one: *)
# C.make_sequence (C.seq2 C.basic_int32 (C.array C.basic_string)) (42l, ["foo"; "bar"]);;
- : OBus_value.V.sequence =
[OBus_value.V.Basic (OBus_value.V.Int32 42l);
 OBus_value.V.Array (OBus_value.T.Basic OBus_value.T.String,
  [OBus_value.V.Basic (OBus_value.V.String "foo");
   OBus_value.V.Basic (OBus_value.V.String "bar")])]

(* Cast a D-Bus value to an ocaml one: *)
# C.cast_sequence (C.seq1 C.basic_string) [V.basic(V.string "foobar")];;
- : string = "foobar"

(* Try to cast a D-Bus value to an ocaml one with the wrong type: *)
# C.cast_sequence (C.seq1 C.basic_string) [V.basic(V.int32 0l)];;
Exception: OBus_value.C.Signature_mismatch.
\end{lstlisting}

\subsection{Errors mapping}

A call to a method may fails. In this case the service sends an error
to the caller.  \dbus errors are mapped to ocaml exceptions by the
\texttt{OBus\_error} module.  Basically, to defines a mapping between
an exception and a \dbus error, here is what you have to do:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
exception My_exn of string

let module M = OBus_error.Register(struct
                                     exception E = My_exn
                                     let name = "org.foo.bar.MyError"
                                   end)
in ()
\end{lstlisting}

  Or, if you use the syntax extension:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
exception My_exn of string
  with obus("org.foo.bar.MyError")
\end{lstlisting}

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Using D-Bus services}

In this section we describe the canonical way of using a \dbus service
with \obus.

\subsection{Defining and using members}

For all types of members (methods, signals and properties), \dbus
provides types to defines them and functions to use these
definitions. A member definition contains all the information about a
member. For example, here is the definition of a method call named
``foo'' on interface ``org.foo.bar'' which takes a string and returns
an 32-bits signed integer:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
open OBus_member

let m_Foo = {
  Method.interface = "org.foo.bar";
  Method.member = "Foo";
  Method.i_args = C.seq1 C.basic_string;
  Method.o_args = C.seq1 C.basic_int32;
  Method.annotations = [];
}
\end{lstlisting}

Once a member is defined, it can be used by the corresponding modules:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
open Lwt
open OBus_members

(* Definition of a method *)
let m_GetId = {
  Method.interface = "org.freedesktop.DBus";
  Method.member = "GetId";
  Method.i_args = C.seq0;
  Method.o_args = C.seq1 C.basic_string;
  Method.annotations = [];
}

(* Definition of a signal *)
let s_NameAcquired = {
  Signal.interface = "org.freedesktop.DBus";
  Signal.member = "NameAcquired";
  Signal.args = C.seq1 (C.basic C.string);
  Signal.annotations = [];
}

lwt () =
  lwt bus = OBus_bus.session () in
  let proxy =
    OBus_proxy.make
      (OBus_peer.make bus "org.freedesktop.DBus")
      ["org"; "freedesktop"; "DBus"]
  in

  (* Call the method we just defined: *)
  lwt id = OBus_method.call m_GetId proxy () in

  (* Register to the signal we just defined: *)
  lwt event = OBus_signal.connect (OBus_signal.make s_NameAcquired proxy) in

  Lwt_react.E.notify_p
    (fun name ->
       Lwt_io.printlf "name acquired: %s" name)
    event;

  Lwt_io.printlf "The message bus id is %s" id
\end{lstlisting}

Of course, writting definitions by hand may be very boring and
error-prone. To avoid that \obus can automatically convert
introspection data into ocaml definitions.

\subsection{Using tools to generate member definitions}

There are two tools that are usefull for client-side code:
\texttt{obus-gen-interface} and \texttt{obus-gen-client}. The first
one converts an xml introspection document (or an idl file) into an
ocaml module containing all the camlized definitions. This generated
file is in fact also needed for server-side code. Note that fiels
produced by \texttt{obus-gen-interface} are not meant to be edited.

The second tool maps members into their ocaml counterpart: methods are
mapped to functions, signals to value of type \texttt{OBus\_signal.t}
and properties to values of type \texttt{OBus\_property.t}.  This
generated file is meant to be edited. For example, you can edit it in
order to change the type of values taken/returned by methods.

\subsection{The \obus IDL language}

Since editing XML is horrible, \obus provides a intermediate language
to write \dbus interfaces. Moreover this language allow you to
automatically converts integers to ocaml variants when needed.

The syntax is pretty simple. Here is an example, taken from \obus
sources (file \texttt{src/oBus\_interfaces.obus}):

\lstset{language=[Objective]Caml}
\begin{lstlisting}
interface org.freedesktop.DBus {
  (** A method definition: *)
  method Hello : () -> (name : string)

  (** Bitwise flags definition: *)
  flag request_name_flags : uint32 {
    0b001: allow_replacement
    0b010: replace_existing
    0b100: do_not_queue
  }

  (** Definition of an enumeration: *)
  enum request_name_result : uint32 {
    1: primary_owner
    2: in_queue
    3: exists
    4: already_owner
  }

  (** A method that use newly defined types: *)
  method RequestName :
    (name : string, flags : request_name_flags)
    ->
    (result : request_name_result)
}
\end{lstlisting}

All \obus tools that accept XML files also accept IDL files. Moreover
it is possible to convert them by using \texttt{obus-idl2xml} and
\texttt{obus-xml2idl}.

\subsection{Name tracking}
\label{name-tracking}

The owner of a on-unique name may change over the time. \obus provides
the \texttt{OBus\_resolver} module to deals with it. The owner is
mapped into a React's signal holding the current owner of a name.

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Writing D-Bus services}

In this section we describe the canonical way of writing \dbus
services with \obus.

Local \dbus objects are represented by values of type
\texttt{OBus\_object.t}. The main operations on objects are: adding an
interface and exporting it on a connection.  Exporting an object means
making it available to all peers reachable from the connection.

In order to add callable methods to objects you have to create
interfaces descriptions (of type \texttt{'a OBus\_object.interface})
and add them to objects.

The canonical way to create interfaces with \obus is to first write
its signature in an XML introspection file or in an \obus idl file,
then convert it into an ocaml definition module with
\texttt{obus-gen-interface} and in a template ocaml source file with
\texttt{obus-gen-server}.

Here is a small example of interface:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
interface org.Foo.Bar {
  method GetApplicationName : () -> (name : string)
    (** Returns the name of the application *)
}
\end{lstlisting}

It is converted with:

\lstset{language=bash}
\begin{lstlisting}
$ obus-gen-interface foobar.obus -o foobar_interfaces
file "foobar_interfaces.ml" written
file "foobar_interfaces.mli" written
$ obus-gen-server foobar.obus -o foobar
file "foobar.ml" written
\end{lstlisting}

Now all that you have to do is to edit the file generated by
\texttt{obus-gen-server} and replace the ``Not implemented'' errors by
your code.

Once it is done, here is how to actually create the object, add the
interface and export it:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
lwt () =
  lwt bus = OBus_bus.session () in

  (* Request a name: *)
  lwt _ = OBus_bus.request_name bus "org.Foo.Bar" in

  (* Create the object: *)
  let obj =
    OBus_object.make
      ~interfaces:[Foobar.Org_Foo_Bar.interface]
      ["plip"]
  in

  (* Attach it some data: *)
  OBus_object.attach obj ();

  (* Export the object on the connection *)
  OBus_object.export bus obj;

  (* Wait forever *)
  fst (wait ())
\end{lstlisting}

Note the you can attach custom data to the object with
\texttt{OBus\_object.attach}.

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{One-to-one communication}

Instead of connection to a message bus, you may want to directly
connects to another application. This can be done with
\texttt{OBus\_connection.of\_addresses}.

If you want to allow other applications to connect to your application
then you have to start a server. Starting a server is very simple, all
you have to do is to call \texttt{OBus\_server.make} with a callback
that will receive new connections.

%% +-----------------------------------------------------------------+
%% | Section                                                         |
%% +-----------------------------------------------------------------+
\section{Low-level use of D-Bus}
\label{lowlevel-section}

This section describes the low-level part of \obus.

\subsection{Message filters}

Message filters are function that are applied to all
incomming/outgoing messages. Filters are of type:

\lstset{language=[Objective]Caml}
\begin{lstlisting}
type filter = OBus_message.t -> OBus_message.t option
\end{lstlisting}

Each filter may use and/or modify the message. If \texttt{None} is
returned the message is dropped.

\subsection{Matching rules}

When using a message bus, an application do not receive messages that
are not destined to it. In order to receive such messages, one need to
add rules on the message bus. All messages matching a rule are sent to
the application which defined that rule.

There are two ways of adding matching rules: by using the module
\texttt{OBus\_bus}, or by using \texttt{OBus\_match}. The functions
\texttt{OBus\_bus.add\_match} and \texttt{OBus\_bus.remove\_match} are
directly mapped to the corresponding methods of the message bus. The
function \texttt{OBus\_match.export} is more clever:

\begin{itemize}
\item it exports only one time duplicated rules,
\item it exports only the most general rules.
\end{itemize}

We say that a rule \texttt{r1} is more general that a rule \texttt{r2}
if all messages matched by \texttt{r2} are also matched by
\texttt{r1}.  For example a rule that accept all messages with
interface field equal to \texttt{foo.bar} is more general that a rule
that accept all messages with interface field equal to
\texttt{foo.bar} and with member field equal to \texttt{plop}.

Note that you must be carefull if you use both modules that
automatically manage rules (such as \texttt{OBus\_signal},
\texttt{OBus\_resolver} or \texttt{OBus\_property}) and
\texttt{OBus\_bus.add\_match} or \texttt{OBus\_bus.remove\_match}.

\subsection{Defining new transports}

A transport is a way of receiving and sending messages. The
\texttt{OBus\_transport} allow to defines new transports. If you want
to create a new transport that use the same serialization format as
default transport, then you can use the \texttt{OBus\_wire} module.

By definning new transports, you can for example write an application
that forward messages over the network in a very few lines of code.

\subsection{Defining new authentication mechanisms}

When openning a connection, before we can send and receive message
over it, \dbus requires a authentication procedure. \obus implements
both client and server side authentication.  The \texttt{OBus\_auth}
allow to write new client and server side authentication mechanisms.

\end{document}
