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
14This document is intended mostly for developers who wish to develop a new GUI
15interface 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
22Until now, I have kept all the Catalog code in the Directory (with the
23exception of dbcheck and bscan). This is because at some point I would like to
24add user level security and access. If we have code spread everywhere such as
25in a GUI this will be more difficult. The other advantage is that any code you
26add to the Director is automatically available to both the tty console program
27and the WX program. The major disadvantage is it increases the size of the
28code -- 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
35Interfacing to an interactive program such as Bacula can be very difficult
36because the interfacing program must interpret all the prompts that may come.
37This can be next to impossible. There are are a number of ways that Bacula is
38designed to facilitate this:
39
40\begin{itemize}
41\item The Bacula network protocol is packet based, and  thus pieces of
42information 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
45than data.
46\item The Director has a number of commands that are  non-interactive. They
47all begin with a period,  and provide things such as the list of all Jobs,
48list of all Clients, list of all Pools, list of  all Storage, ... Thus the GUI
49interface can get  to virtually all information that the Director has  in a
50deterministic way. See  \lt{}bacula-source\gt{}/src/dird/ua\_dotcmds.c for
51more details on this.
52\item Most console commands allow all the arguments to  be specified on the
53command line: e.g.  {\bf run job=NightlyBackup level=Full}
54\end{itemize}
55
56One of the first things to overcome is to be able to establish a conversation
57with the Director. Although you can write all your own code, it is probably
58easier to use the Bacula subroutines. The following code is used by the
59Console program to begin a conversation.
60
61\footnotesize
62\begin{verbatim}
63static BSOCK *UA_sock = NULL;
64static 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
88Then 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
99For a GUI program things will be a bit more complicated. Basically in the very
100inner loop, you will need to check and see if any output is available on the
101UA\_sock. For an example, please take a look at the WX GUI interface code
102in: \lt{bacula-source/src/wx-console}
103
104\section{Bvfs API}
105\label{sec:bvfs}
106
107To 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
125You can use \texttt{limit=xxx} and \texttt{offset=yyy} to limit the amount of
126data 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}
133