<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2008 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>loadPlugin</TITLE>
<META NAME="description" CONTENT="loadPlugin">
<META NAME="keywords" CONTENT="developers">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="developers.css">
<LINK REL="next" HREF="Plugin_Entry_Points.html">
<LINK REL="previous" HREF="Loading_Plugins.html">
<LINK REL="up" HREF="Bacula_FD_Plugin_API.html">
<LINK REL="next" HREF="Plugin_Entry_Points.html">
</HEAD>
<BODY >
<!--Navigation Panel-->
<A NAME="tex2html684"
HREF="Plugin_Entry_Points.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html678"
HREF="Bacula_FD_Plugin_API.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html672"
HREF="Loading_Plugins.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html680"
HREF="Contents.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html682"
HREF="GNU_Free_Documentation_Lice.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html685"
HREF="Plugin_Entry_Points.html">Plugin Entry Points</A>
<B> Up:</B> <A NAME="tex2html679"
HREF="Bacula_FD_Plugin_API.html">Bacula FD Plugin API</A>
<B> Previous:</B> <A NAME="tex2html673"
HREF="Loading_Plugins.html">Loading Plugins</A>
<B> <A NAME="tex2html681"
HREF="Contents.html">Contents</A></B>
<B> <A NAME="tex2html683"
HREF="GNU_Free_Documentation_Lice.html">Index</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION00430000000000000000">
loadPlugin</A>
</H1>
As previously mentioned, the <B>loadPlugin</B> entry point in the plugin
is called immediately after Bacula loads the plugin when the File daemon
itself is first starting. This entry point is only called once during the
execution of the File daemon. In calling the
plugin, the first two arguments are information from Bacula that
is passed to the plugin, and the last two arguments are information
about the plugin that the plugin must return to Bacula. The call is:
<P>
<PRE>
bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
</PRE>
<P>
and the arguments are:
<P>
<DL>
<DT><STRONG>lbinfo</STRONG></DT>
<DD>This is information about Bacula in general. Currently, the only value
defined in the bInfo structure is the version, which is the Bacula plugin
interface version, currently defined as 1. The <B>size</B> is set to the
byte size of the structure. The exact definition of the bInfo structure
as of this writing is:
<P>
<PRE>
typedef struct s_baculaInfo {
uint32_t size;
uint32_t version;
} bInfo;
</PRE>
<P>
</DD>
<DT><STRONG>lbfuncs</STRONG></DT>
<DD>The bFuncs structure defines the callback entry points within Bacula
that the plugin can use register events, get Bacula values, set
Bacula values, and send messages to the Job output or debug output.
<P>
The exact definition as of this writing is:
<PRE>
typedef struct s_baculaFuncs {
uint32_t size;
uint32_t version;
bRC (*registerBaculaEvents)(bpContext *ctx, ...);
bRC (*getBaculaValue)(bpContext *ctx, bVariable var, void *value);
bRC (*setBaculaValue)(bpContext *ctx, bVariable var, void *value);
bRC (*JobMessage)(bpContext *ctx, const char *file, int line,
int type, utime_t mtime, const char *fmt, ...);
bRC (*DebugMessage)(bpContext *ctx, const char *file, int line,
int level, const char *fmt, ...);
void *(*baculaMalloc)(bpContext *ctx, const char *file, int line,
size_t size);
void (*baculaFree)(bpContext *ctx, const char *file, int line, void *mem);
} bFuncs;
</PRE>
<P>
We will discuss these entry points and how to use them a bit later when
describing the plugin code.
<P>
</DD>
<DT><STRONG>pInfo</STRONG></DT>
<DD>When the loadPlugin entry point is called, the plugin must initialize
an information structure about the plugin and return a pointer to
this structure to Bacula.
<P>
The exact definition as of this writing is:
<P>
<PRE>
typedef struct s_pluginInfo {
uint32_t size;
uint32_t version;
const char *plugin_magic;
const char *plugin_license;
const char *plugin_author;
const char *plugin_date;
const char *plugin_version;
const char *plugin_description;
} pInfo;
</PRE>
<P>
Where:
<DL>
<DT><STRONG>version</STRONG></DT>
<DD>is the current Bacula defined plugin interface version, currently
set to 1. If the interface version differs from the current version of
Bacula, the plugin will not be run (not yet implemented).
</DD>
<DT><STRONG>plugin_magic</STRONG></DT>
<DD>is a pointer to the text string "*FDPluginData*", a
sort of sanity check. If this value is not specified, the plugin
will not be run (not yet implemented).
</DD>
<DT><STRONG>plugin_license</STRONG></DT>
<DD>is a pointer to a text string that describes the
plugin license. Bacula will only accept compatible licenses (not yet
implemented).
</DD>
<DT><STRONG>plugin_author</STRONG></DT>
<DD>is a pointer to the text name of the author of the program.
This string can be anything but is generally the author's name.
</DD>
<DT><STRONG>plugin_date</STRONG></DT>
<DD>is the pointer text string containing the date of the plugin.
This string can be anything but is generally some human readable form of
the date.
</DD>
<DT><STRONG>plugin_version</STRONG></DT>
<DD>is a pointer to a text string containing the version of
the plugin. The contents are determined by the plugin writer.
</DD>
<DT><STRONG>plugin_description</STRONG></DT>
<DD>is a pointer to a string describing what the
plugin does. The contents are determined by the plugin writer.
</DD>
</DL>
<P>
The pInfo structure must be defined in static memory because Bacula does not
copy it and may refer to the values at any time while the plugin is
loaded. All values must be supplied or the plugin will not run (not yet
implemented). All text strings must be either ASCII or UTF-8 strings that
are terminated with a zero byte.
<P>
</DD>
<DT><STRONG>pFuncs</STRONG></DT>
<DD>When the loadPlugin entry point is called, the plugin must initialize
an entry point structure about the plugin and return a pointer to
this structure to Bacula. This structure contains pointer to each
of the entry points that the plugin must provide for Bacula. When
Bacula is actually running the plugin, it will call the defined
entry points at particular times. All entry points must be defined.
<P>
The pFuncs structure must be defined in static memory because Bacula does not
copy it and may refer to the values at any time while the plugin is
loaded.
<P>
The exact definition as of this writing is:
<P>
<PRE>
typedef struct s_pluginFuncs {
uint32_t size;
uint32_t version;
bRC (*newPlugin)(bpContext *ctx);
bRC (*freePlugin)(bpContext *ctx);
bRC (*getPluginValue)(bpContext *ctx, pVariable var, void *value);
bRC (*setPluginValue)(bpContext *ctx, pVariable var, void *value);
bRC (*handlePluginEvent)(bpContext *ctx, bEvent *event, void *value);
bRC (*startBackupFile)(bpContext *ctx, struct save_pkt *sp);
bRC (*endBackupFile)(bpContext *ctx);
bRC (*startRestoreFile)(bpContext *ctx, const char *cmd);
bRC (*endRestoreFile)(bpContext *ctx);
bRC (*pluginIO)(bpContext *ctx, struct io_pkt *io);
bRC (*createFile)(bpContext *ctx, struct restore_pkt *rp);
bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp);
bRC (*checkFile)(bpContext *ctx, char *fname);
} pFuncs;
</PRE>
<P>
The details of the entry points will be presented in
separate sections below.
<P>
Where:
<DL>
<DT><STRONG>size</STRONG></DT>
<DD>is the byte size of the structure.
</DD>
<DT><STRONG>version</STRONG></DT>
<DD>is the plugin interface version currently set to 3.
</DD>
</DL>
<P>
Sample code for loadPlugin:
<PRE>
bfuncs = lbfuncs; /* set Bacula funct pointers */
binfo = lbinfo;
*pinfo = &pluginInfo; /* return pointer to our info */
*pfuncs = &pluginFuncs; /* return pointer to our functions */
return bRC_OK;
</PRE>
<P>
where pluginInfo and pluginFuncs are statically defined structures.
See bpipe-fd.c for details.
<P>
</DD>
</DL>
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html684"
HREF="Plugin_Entry_Points.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html678"
HREF="Bacula_FD_Plugin_API.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html672"
HREF="Loading_Plugins.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html680"
HREF="Contents.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html682"
HREF="GNU_Free_Documentation_Lice.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html685"
HREF="Plugin_Entry_Points.html">Plugin Entry Points</A>
<B> Up:</B> <A NAME="tex2html679"
HREF="Bacula_FD_Plugin_API.html">Bacula FD Plugin API</A>
<B> Previous:</B> <A NAME="tex2html673"
HREF="Loading_Plugins.html">Loading Plugins</A>
<B> <A NAME="tex2html681"
HREF="Contents.html">Contents</A></B>
<B> <A NAME="tex2html683"
HREF="GNU_Free_Documentation_Lice.html">Index</A></B>
<!--End of Navigation Panel-->
<ADDRESS>
2012-01-24
</ADDRESS>
</BODY>
</HTML>
