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.
 
-\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 = <command-string>
+       }
+       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}