From c442eafd642266f1ebc37ae847a3478ba6098221 Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Thu, 18 Sep 2008 16:49:54 +0000 Subject: [PATCH] Update plugin API doc --- docs/manuals/en/concepts/concepts.kilepr | 4 +- docs/manuals/en/concepts/newfeatures.tex | 164 +++++++++++++++++++++-- 2 files changed, 158 insertions(+), 10 deletions(-) diff --git a/docs/manuals/en/concepts/concepts.kilepr b/docs/manuals/en/concepts/concepts.kilepr index 18ced57d..c910c079 100644 --- a/docs/manuals/en/concepts/concepts.kilepr +++ b/docs/manuals/en/concepts/concepts.kilepr @@ -161,10 +161,10 @@ order=-1 [item:newfeatures.tex] archive=true -column=8 +column=67 encoding= highlight=LaTeX -line=32 +line=850 open=true order=0 diff --git a/docs/manuals/en/concepts/newfeatures.tex b/docs/manuals/en/concepts/newfeatures.tex index 052614db..6ef277cc 100644 --- a/docs/manuals/en/concepts/newfeatures.tex +++ b/docs/manuals/en/concepts/newfeatures.tex @@ -631,7 +631,11 @@ a real plugin, which is still rather simple and small. When actually writing your own plugin, you may use the example-plugin-fd.c code as a template for your code. -\section{Bacula FD Plugin API} + +%% +%% + +\chapter{Bacula FD Plugin API} To write a Bacula plugin, you cread a dynamic shared object program (or dll on Win32) with a particular name and two entry points, place it in the {\bf Plugins Directory}, and when the FD @@ -679,7 +683,7 @@ shared object so that the plugin can use much more of Bacula's infrastructure, but for this first cut, we have tried to minimize the dependence on Bacula. -\subsection{loadPlugin} +\section{loadPlugin} As previously mentioned, the {\bf loadPlugin} entry point in the plugin is called immediately after Bacula loads the plugin. In calling the plugin, the first two arguments are information from Bacula that @@ -804,11 +808,24 @@ typedef struct s_pluginFuncs { } pFuncs; \end{verbatim} +The details of the entry points will be presented in +separate sections below. + Where: \begin{description} \item [size] is the size of the structure. \item [version] is the plugin interface version. - \item [newPlugin] is the entry point that Bacula will call + \end{description} + +\end{description} + +\section{Plugin Entry Points} +This section will describe each of the entry points that +the plugin must provide for Bacula, when they are called +and their arguments. + +\subsection{newPlugin(bpContext *ctx)} + This is the entry point that Bacula will call when a new instance of the plugin is created. This typically happens at the beginning of a Job. If 10 Jobs are running simultaneously, there will be at least 10 instances of the @@ -835,18 +852,22 @@ typedef struct s_bpContext { is Bacula's private context pointer for this instance of this plugin. - \item [freePlugin] this entry point is called when the +\subsection{freePlugin(bpContext *ctx)} + This entry point is called when the this instance of the plugin is no longer needed (the Job is ending), and the plugin should release any memory it may have allocated for the pContext. - \item [getPluginValue] Bacula will call this entry point to get +\subsection{getPluginValue(bpContext *ctx, pVariable var, void *value)} +Bacula will call this entry point to get a value from the plugin. This entry point is currently not called. - \item [setPluginValue] Bacula will call this entry point to set +\subsection{setPluginValue(bpContext *ctx, pVariable var, void *value)} + Bacula will call this entry point to set a value in the plugin. This entry point is currently not called. - \item [handlePluginEvent] This entry point is called when Bacula +\subsection{handlePluginEvent(bpContext *ctx, bEvent *event, void *value)} + This entry point is called when Bacula encounters certain events. Bacula passes the pointer to an event structure (bEvent), which currently has one item, the eventType: @@ -882,6 +903,133 @@ typedef enum { \end{verbatim} Most of which are pretty explanatory. - \end{description} +\begin{description} + \item [bEventJobStart] is called whenever a Job starts. + \item [bEventJobEnd] is called whenever a Job ends. + \item [bEventStartBackupJob] is called when a Backup Job begins. + \item [bEventEndBackupJob] is called when a Backup Job ends. + \item [bEventStartRestoreJob] is called when a Restore Job starts. + \item [bEventEndRestoreJob] is called when a Restore Job ends. + \item [bEventStartVerifyJob] is called when a Verify Job starts. + \item [bEventEndVerifyJob] is called when a Verify Job ends. + \item [bEventBackupCommand] + \item [bEventRestoreCommand] + \item [bEventLevel] is called when the level is set for a new Job. + \item [bEventSince] is called whent the since time is set for a new Job. \end{description} + +\subsection{startBackupFile(bpContext *ctx, struct save\_pkt *sp)} +Called when beginning the backup of a file. + +\begin{verbatim} + struct save_pkt { + char *fname; /* Full path and filename */ + char *link; /* Link name if any */ + struct stat statp; /* System stat() packet for file */ + int32_t type; /* FT_xx for this file */ + uint32_t flags; /* Bacula internal flags */ + bool portable; /* set if data format is portable */ + char *cmd; /* command */ +}; + +\end{verbatim} + + +\subsection{endBackupFile(bpContext *ctx)} +Called at the end of backing up a file. + +\subsection{startRestoreFile(bpContext *ctx, const char *cmd)} +Called when beginning to restore a file. + +\begin{verbatim} + struct restore_pkt { + int32_t stream; /* attribute stream id */ + int32_t data_stream; /* id of data stream to follow */ + int32_t type; /* file type FT */ + int32_t file_index; /* file index */ + int32_t LinkFI; /* file index to data if hard link */ + uid_t uid; /* userid */ + struct stat statp; /* decoded stat packet */ + const char *attrEx; /* extended attributes if any */ + const char *ofname; /* output filename */ + const char *olname; /* output link name */ + const char *where; /* where */ + const char *RegexWhere; /* regex where */ + int replace; /* replace flag */ +}; +\end{verbatim} + + +\subsection{endRestoreFile(bpContext *ctx)} +Called when done restoring a file. + +\subsection{pluginIO(bpContext *ctx, struct io\_pkt *io)} +Called to do the input (backup) or output (restore) of data from or to a +file. + +\begin{verbatim} + enum { + IO_OPEN = 1, + IO_READ = 2, + IO_WRITE = 3, + IO_CLOSE = 4, + IO_SEEK = 5 +}; + +struct io_pkt { + int32_t func; /* Function code */ + int32_t count; /* read/write count */ + mode_t mode; /* permissions for created files */ + int32_t flags; /* open flags (e.g. O_WRONLY ...) */ + char *buf; /* read/write buffer */ + int32_t status; /* return status */ + int32_t io_errno; /* errno code */ + int32_t whence; + boffset_t offset; +}; + +\end{verbatim} + + +\subsection{createFile(bpContext *ctx, struct restore\_pkt *rp)} +Called to create a file before restoring the data. + +\begin{verbatim} + +struct restore_pkt { + int32_t stream; /* attribute stream id */ + int32_t data_stream; /* id of data stream to follow */ + int32_t type; /* file type FT */ + int32_t file_index; /* file index */ + int32_t LinkFI; /* file index to data if hard link */ + uid_t uid; /* userid */ + struct stat statp; /* decoded stat packet */ + const char *attrEx; /* extended attributes if any */ + const char *ofname; /* output filename */ + const char *olname; /* output link name */ + const char *where; /* where */ + const char *RegexWhere; /* regex where */ + int replace; /* replace flag */ +}; +\end{verbatim} + +\subsection{setFileAttributes(bpContext *ctx, struct restore\_pkt *rp)} +\begin{verbatim} + +struct restore_pkt { + int32_t stream; /* attribute stream id */ + int32_t data_stream; /* id of data stream to follow */ + int32_t type; /* file type FT */ + int32_t file_index; /* file index */ + int32_t LinkFI; /* file index to data if hard link */ + uid_t uid; /* userid */ + struct stat statp; /* decoded stat packet */ + const char *attrEx; /* extended attributes if any */ + const char *ofname; /* output filename */ + const char *olname; /* output link name */ + const char *where; /* where */ + const char *RegexWhere; /* regex where */ + int replace; /* replace flag */ +}; +\end{verbatim} \ No newline at end of file -- 2.39.5