git.sur5r.net Git - bacula/docs/blob - docs/manuals/en/developers/gui-interface.tex

   1 %%
   2 %%
   3
   4 \chapter*{Implementing a GUI Interface}
   5 \label{_ChapterStart}
   6 \index[general]{Interface!Implementing a Bacula GUI }
   7 \index[general]{Implementing a Bacula GUI Interface }
   8 \addcontentsline{toc}{section}{Implementing a Bacula GUI Interface}
   9
  10 \section{General}
  11 \index[general]{General }
  12 \addcontentsline{toc}{subsection}{General}
  13
  14 This document is intended mostly for developers who wish to develop a new GUI
  15 interface to {\bf Bacula}.
  16
  17 \subsection{Minimal Code in Console Program}
  18 \index[general]{Program!Minimal Code in Console }
  19 \index[general]{Minimal Code in Console Program }
  20 \addcontentsline{toc}{subsubsection}{Minimal Code in Console Program}
  21
  22 Until now, I have kept all the Catalog code in the Directory (with the
  23 exception of dbcheck and bscan). This is because at some point I would like to
  24 add user level security and access. If we have code spread everywhere such as
  25 in a GUI this will be more difficult. The other advantage is that any code you
  26 add to the Director is automatically available to both the tty console program
  27 and the WX program. The major disadvantage is it increases the size of the
  28 code -- however, compared to Networker the Bacula Director is really tiny.
  29
  30 \subsection{GUI Interface is Difficult}
  31 \index[general]{GUI Interface is Difficult }
  32 \index[general]{Difficult!GUI Interface is }
  33 \addcontentsline{toc}{subsubsection}{GUI Interface is Difficult}
  34
  35 Interfacing to an interactive program such as Bacula can be very difficult
  36 because the interfacing program must interpret all the prompts that may come.
  37 This can be next to impossible. There are are a number of ways that Bacula is
  38 designed to facilitate this:
  39
  40 \begin{itemize}
  41 \item The Bacula network protocol is packet based, and  thus pieces of
  42 information sent can be ASCII or binary.
  43 \item The packet interface permits knowing where the end of  a list is.
  44 \item The packet interface permits special ``signals''  to be passed rather
  45 than data.
  46 \item The Director has a number of commands that are  non-interactive. They
  47 all begin with a period,  and provide things such as the list of all Jobs,
  48 list of all Clients, list of all Pools, list of  all Storage, ... Thus the GUI
  49 interface can get  to virtually all information that the Director has  in a
  50 deterministic way. See  \lt{}bacula-source\gt{}/src/dird/ua\_dotcmds.c for
  51 more details on this.
  52 \item Most console commands allow all the arguments to  be specified on the
  53 command line: e.g.  {\bf run job=NightlyBackup level=Full}
  54 \end{itemize}
  55
  56 One of the first things to overcome is to be able to establish a conversation
  57 with the Director. Although you can write all your own code, it is probably
  58 easier to use the Bacula subroutines. The following code is used by the
  59 Console program to begin a conversation.
  60
  61 \footnotesize
  62 \begin{verbatim}
  63 static BSOCK *UA_sock = NULL;
  64 static JCR *jcr;
  65 ...
  66   read-your-config-getting-address-and-pasword;
  67   UA_sock = bnet_connect(NULL, 5, 15, "Director daemon", dir->address,
  68                           NULL, dir->DIRport, 0);
  69    if (UA_sock == NULL) {
  70       terminate_console(0);
  71       return 1;
  72    }
  73    jcr.dir_bsock = UA_sock;
  74    if (!authenticate_director(\&jcr, dir)) {
  75       fprintf(stderr, "ERR=%s", UA_sock->msg);
  76       terminate_console(0);
  77       return 1;
  78    }
  79    read_and_process_input(stdin, UA_sock);
  80    if (UA_sock) {
  81       bnet_sig(UA_sock, BNET_TERMINATE); /* send EOF */
  82       bnet_close(UA_sock);
  83    }
  84    exit 0;
  85 \end{verbatim}
  86 \normalsize
  87
  88 Then the read\_and\_process\_input routine looks like the following:
  89
  90 \footnotesize
  91 \begin{verbatim}
  92    get-input-to-send-to-the-Director;
  93    bnet_fsend(UA_sock, "%s", input);
  94    stat = bnet_recv(UA_sock);
  95    process-output-from-the-Director;
  96 \end{verbatim}
  97 \normalsize
  98
  99 For a GUI program things will be a bit more complicated. Basically in the very
 100 inner loop, you will need to check and see if any output is available on the
 101 UA\_sock. For an example, please take a look at the WX GUI interface code
 102 in: \lt{bacula-source/src/wx-console}
 103
 104 \section{Bvfs API}
 105 \label{sec:bvfs}
 106
 107 To help developers of restore GUI interfaces, we have added new \textsl{dot
 108   commands} that permit browsing the catalog in a very simple way.
 109
 110 \begin{itemize}
 111 \item \texttt{.bvfs\_update [jobid=x,y,z]} This command is required to update
 112   the Bvfs cache in the catalog. You need to run it before any access to the
 113   Bvfs layer.
 114
 115 \item \texttt{.bvfs\_lsdirs jobid=x,y,z path=/path | pathid=101} This command
 116   will list all directories in the specified \texttt{path} or
 117   \texttt{pathid}. Using \texttt{pathid} avoids problems with character
 118   encoding of path/filenames.
 119
 120 \item \texttt{.bvfs\_lsfiles jobid=x,y,z path=/path | pathid=101} This command
 121   will list all files in the specified \texttt{path} or \texttt{pathid}. Using
 122   \texttt{pathid} avoids problems with character encoding.
 123 \end{itemize}
 124
 125 You can use \texttt{limit=xxx} and \texttt{offset=yyy} to limit the amount of
 126 data that will be displayed.
 127
 128 \begin{verbatim}
 129 * .bvfs_update jobid=1,2
 130 * .bvfs_update
 131 * .bvfs_lsdir path=/ jobid=1,2
 132 \end{verbatim}