Add some notes about CF_CORE and new Options{} Plugin

diff --git a/docs/manuals/en/developers/pluginAPI.tex b/docs/manuals/en/developers/pluginAPI.tex
index 386aad18e933ba6083c365c2b0216482cfbb9676..42103f207f9d14f0582b438733a4b330ed39eedd 100644 (file)
--- 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.
 
 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
 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}
 
     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 = <command-string>
+       }
+       File = /
+    }
+}
+\end{verbatim}

 
 \section{Loading Plugins}
 Once the File daemon loads the plugins, it asks the OS for the
 
 \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_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}
 
 } bRC;
 \end{verbatim}
 


@@ -379,13 +405,27 @@ typedef enum {
   bEventRestoreCommand                  = 10,
   bEventLevel                           = 11,
   bEventSince                           = 12,
   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,
   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}
 } 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
    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] 
 
 
 \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). 
 
   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
 \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 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}
    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_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}
 
 };
 \end{verbatim}