From: <ke...@us...> - 2008-09-18 16:49:44
|
Revision: 7612 http://bacula.svn.sourceforge.net/bacula/?rev=7612&view=rev Author: kerns Date: 2008-09-18 16:49:54 +0000 (Thu, 18 Sep 2008) Log Message: ----------- Update plugin API doc Modified Paths: -------------- trunk/docs/manuals/en/concepts/concepts.kilepr trunk/docs/manuals/en/concepts/newfeatures.tex Modified: trunk/docs/manuals/en/concepts/concepts.kilepr =================================================================== --- trunk/docs/manuals/en/concepts/concepts.kilepr 2008-09-18 16:06:43 UTC (rev 7611) +++ trunk/docs/manuals/en/concepts/concepts.kilepr 2008-09-18 16:49:54 UTC (rev 7612) @@ -161,10 +161,10 @@ [item:newfeatures.tex] archive=true -column=8 +column=67 encoding= highlight=LaTeX -line=32 +line=850 open=true order=0 Modified: trunk/docs/manuals/en/concepts/newfeatures.tex =================================================================== --- trunk/docs/manuals/en/concepts/newfeatures.tex 2008-09-18 16:06:43 UTC (rev 7611) +++ trunk/docs/manuals/en/concepts/newfeatures.tex 2008-09-18 16:49:54 UTC (rev 7612) @@ -631,7 +631,11 @@ 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 @@ 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 @@ } 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 @@ 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 @@ \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 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |