load Plugin

As previously mentioned, the loadPlugin 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:

bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)

and the arguments are:

lbinfo

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 size is set to the byte size of the structure. The exact definition of the bInfo structure as of this writing is:

typedef struct s_baculaInfo {
   uint32_t size;
   uint32_t version;
} bInfo;

lbfuncs

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.

The exact definition as of this writing is:

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);
   bRC (*AddExclude)(bpContext *ctx, const char *file);
   bRC (*AddInclude)(bpContext *ctx, const char *file);
   bRC (*AddOptions)(bpContext *ctx, const char *opts);
   bRC (*AddRegex)(bpContext *ctx, const char *item, int type);
   bRC (*AddWild)(bpContext *ctx, const char *item, int type);
   bRC (*NewOptions)(bpContext *ctx);
   bRC (*NewInclude)(bpContext *ctx);
   bRC (*NewPreInclude)(bpContext *ctx);
   bRC (*checkChanges)(bpContext *ctx, struct save_pkt *sp);
   bRC (*AcceptFile)(bpContext *ctx, struct save_pkt *sp); /* Need fname and statp */
   bRC (*getAccurateAttribs)(bpContext *ctx, accurate_attribs_pkt *att);
   bRC (*AddPlugin)(bpContext *ctx, const char *file);
} bFuncs;

We will discuss these entry points and how to use them a bit later when describing the plugin code.

pInfo

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.

The exact definition as of this writing is:

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;

Where:

version: 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).
plugin_magic: 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).
plugin_license: is a pointer to a text string that describes the plugin license. Bacula will only accept compatible licenses (not yet implemented).
plugin_author: 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.
plugin_date: 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.
plugin_version: is a pointer to a text string containing the version of the plugin. The contents are determined by the plugin writer.
plugin_description: is a pointer to a string describing what the plugin does. The contents are determined by the plugin writer.

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.

pFuncs

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.

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.

The exact definition as of this writing is:

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);
   bRC (*handleXACLdata)(bpContext *ctx, struct xacl_pkt *xacl);
   bRC (*restoreFileList)(bpContext *ctx, struct restore_filelist_pkt *rp);
   bRC (*checkStream)(bpContext *ctx, struct stream_pkt *sp);
   bRC (*queryParameter)(bpContext *ctx, struct query_pkt *qp);
   bRC (*metadataRestore)(bpContext *ctx, struct meta_pkt *mp);
   bRC (*startVerifyFile)(bpContext *ctx, struct restore_pkt *rp);
   bRC (*endVerifyFile)(bpContext *ctx);
} pFuncs;

The details of the entry points will be presented in separate sections below.

Where:

size: is the byte size of the structure.
version: is the plugin interface version currently set to 3.

Sample code for loadPlugin:

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;

where pluginInfo and pluginFuncs are statically defined structures. See bpipe-fd.c for details.

Possible Next Steps

Go to Plugin EntryPoints.

Go back to Bacula FD Plugin API.

Go back to Developer Guide.