From 7c5060af4e8c2bd6ae6014ada131189bbf55c7ab Mon Sep 17 00:00:00 2001 From: Eric Bollengier Date: Thu, 10 Nov 2011 20:41:51 +0100 Subject: [PATCH] Add some notes about CF_CORE and new Options{} Plugin --- docs/manuals/en/developers/pluginAPI.tex | 65 +++++++++++++++++++++--- 1 file changed, 58 insertions(+), 7 deletions(-) diff --git a/docs/manuals/en/developers/pluginAPI.tex b/docs/manuals/en/developers/pluginAPI.tex index 386aad18..42103f20 100644 --- a/docs/manuals/en/developers/pluginAPI.tex +++ b/docs/manuals/en/developers/pluginAPI.tex @@ -8,8 +8,8 @@ Win32) with a particular name and two exported entry points, place it in the the {\bf Client} resource, and when the FD starts, it will load all the plugins that end with {\bf -fd.so} (or {\bf -fd.dll} on Win32) found in that directory. -\section{Normal vs Command Plugins} -In general, there are two ways that plugins are called. The first way, is when +\section{Normal vs Command vs Options Plugins} +In general, there are three ways that plugins are called. The first way, is when a particular event is detected in Bacula, it will transfer control to each plugin that is loaded in turn informing the plugin of the event. This is very similar to how a {\bf RunScript} works, and the events are very similar. Once @@ -48,6 +48,28 @@ The important features of the command plugin entry points are: so that it can be told what to backup/restore. \end{itemize} +The third type of plugin is the Options Plugin, this kind of plugin is useful +to implement some custom filter on data. For example, you can implement a +compression algorithm in a very simple way. Bacula will call this plugin for +each file that is selected in a FileSet (according to +Wild/Regex/Exclude/Include rules). As with all plugins, it gets notified of +important events as noted above (details described below), but in addition, +this kind of plugin can be placed in a Options group, which is a: + +\begin{verbatim} + FileSet { + Name = TestFS + Include { + Options { + Compression = GZIP1 + Signature = MD5 + Wild = "*.txt" + Plugin = + } + File = / + } +} +\end{verbatim} \section{Loading Plugins} Once the File daemon loads the plugins, it asks the OS for the @@ -104,6 +126,10 @@ typedef enum { bRC_Stop = 1, /* Stop calling other plugins */ bRC_Error = 2, /* Some kind of error */ bRC_More = 3, /* More files to backup */ + bRC_Term = 4, /* Unload me */ + bRC_Seen = 5, /* Return code from checkFiles */ + bRC_Core = 6, /* Let Bacula core handles this file */ + bRC_Skip = 7, /* Skip the proposed file */ } bRC; \end{verbatim} @@ -379,13 +405,27 @@ typedef enum { bEventRestoreCommand = 10, bEventLevel = 11, bEventSince = 12, - bEventCancelCommand = 13, - bEventVssBackupAddComponents = 14, + bEventCancelCommand = 13, /* Executed by another thread */ + + /* Just before bEventVssPrepareSnapshot */ + bEventVssBackupAddComponents = 14, + bEventVssRestoreLoadComponentMetadata = 15, bEventVssRestoreSetComponentsSelected = 16, bEventRestoreObject = 17, bEventEndFileSet = 18, - bEventPluginCommand = 19 + bEventPluginCommand = 19, + bEventVssBeforeCloseRestore = 21, + + /* Add drives to VSS snapshot + * argument: char[27] drivelist + * You need to add them without duplicates, + * see fd_common.h add_drive() copy_drives() to get help + */ + bEventVssPrepareSnapshot = 22, + bEventOptionPlugin = 23, + bEventHandleBackupFile = 24 /* Used with Options Plugin */ + } bEventType; \end{verbatim} @@ -445,7 +485,8 @@ Most of the above are self-explanatory. value is a time\_t time at which the last job was run. \item [bEventCancelCommand] is called whenever the currently - running Job is cancelled + running Job is cancelled. Be warned that this event is sent by a different + thread. \item [bEventVssBackupAddComponents] @@ -453,6 +494,10 @@ Most of the above are self-explanatory. current FileSet. The event will be sent only on plugin specifed in the command. The argument is the PluginCommand (not valid after the call). +\item [bEventHandleBackupFile] is called for each file of a FileSet when + using a Options Plugin. If the plugin returns CF_OK, it will be used for the + backup, if it returns CF_SKIP, the file will be skipped. Anything else will + backup the file with Bacula core functions. \end{description} During each of the above calls, the plugin receives either no specific value or @@ -480,6 +525,11 @@ struct save_pkt { uint32_t flags; /* Bacula internal flags */ bool portable; /* set if data format is portable */ char *cmd; /* command */ + uint32_t delta_seq; /* Delta sequence number */ + char *object_name; /* Object name to create */ + char *object; /* restore object data to save */ + int32_t object_len; /* restore object length */ + int32_t index; /* restore object index */ int32_t pkt_end; /* end packet sentinel */ }; \end{verbatim} @@ -585,7 +635,8 @@ This call must return one of the following values: CF_SKIP = 1, /* skip file (not newer or something) */ CF_ERROR, /* error creating file */ CF_EXTRACT, /* file created, data to extract */ - CF_CREATED /* file created, no data to extract */ + CF_CREATED, /* file created, no data to extract */ + CF_CORE /* let bacula core handles the file creation */ }; \end{verbatim} -- 2.39.5