handlePluginEvent(bpContext ctx, bEvent event, void *value)

This entry point is called when Bacula encounters certain events (discussed below). This is, in fact, the main way that most plugins get control when a Job runs and how they know what is happening in the job. It can be likened to the RunScript feature that calls external programs and scripts. When the plugin is called, Bacula passes it the pointer to an event structure (bEvent), which currently has one item, the eventType:

typedef struct s_bEvent {
   uint32_t eventType;
} bEvent;

which defines what event has been triggered, and for each event, Bacula will pass a pointer to a value associated with that event. If no value is associated with a particular event, Bacula will pass a NULL pointer, so the plugin must be careful to always check value pointer prior to dereferencing it.

The current list of events are:

typedef enum {
  bEventJobStart                        = 1,
  bEventJobEnd                          = 2,
  bEventStartBackupJob                  = 3,
  bEventEndBackupJob                    = 4,
  bEventStartRestoreJob                 = 5,
  bEventEndRestoreJob                   = 6,
  bEventStartVerifyJob                  = 7,
  bEventEndVerifyJob                    = 8,
  bEventBackupCommand                   = 9,
  bEventRestoreCommand                  = 10,
  bEventLevel                           = 11,
  bEventSince                           = 12,
  bEventCancelCommand                   = 13,  /* Executed by another thread */

  /* Just before bEventVssPrepareSnapshot */
  bEventVssBackupAddComponents          = 14,

  bEventVssRestoreLoadComponentMetadata = 15,
  bEventVssRestoreSetComponentsSelected = 16,
  bEventRestoreObject                   = 17,
  bEventEndFileSet                      = 18,
  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;

Most of the above are self-explanatory.

bEventJobStart

is called whenever a Job starts. The value passed is a pointer to a string that contains: “Jobid=nnn Job=job-name”. Where nnn will be replaced by the JobId and job-name will be replaced by the Job name. The variable is temporary so if you need the values, you must copy them.

bEventJobEnd

is called whenever a Job ends. No value is passed.

bEventStartBackupJob

is called when a Backup Job begins. No value is passed.

bEventEndBackupJob

is called when a Backup Job ends. No value is passed.

bEventStartRestoreJob

is called when a Restore Job starts. No value is passed.

bEventEndRestoreJob

is called when a Restore Job ends. No value is passed.

bEventStartVerifyJob

is called when a Verify Job starts. No value is passed.

bEventEndVerifyJob

is called when a Verify Job ends. No value is passed.

bEventBackupCommand

is called prior to the bEventStartBackupJob and the plugin is passed the command string (everything after the equal sign in “Plugin =” as the value.

Note, if you intend to backup a file, this is an important first point to write code that copies the command string passed into your pContext area so that you will know that a backup is being performed and you will know the full contents of the “Plugin =” command (i.e. what to backup and what virtual filename the user wants to call it.

bEventRestoreCommand

is called prior to the bEventStartRestoreJob and the plugin is passed the command string (everything after the equal sign in “Plugin =” as the value.

See the notes above concerning backup and the command string. This is the point at which Bacula passes you the original command string that was specified during the backup, so you will want to save it in your pContext area for later use when Bacula calls the plugin again.

bEventLevel

is called when the level is set for a new Job. The value is a 32 bit integer stored in the void*, which represents the Job Level code.

bEventSince

is called when the since time is set for a new Job. The value is a time_t time at which the last job was run.

bEventCancelCommand

is called whenever the currently running Job is cancelled. Be warned that this event is sent by a different thread.

bEventVssBackupAddComponents

bEventPluginCommand

is called for each PluginCommand present in the current FileSet. The event will be sent only on plugin specifed in the command. The argument is the PluginCommand (not valid after the call).

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.

During each of the above calls, the plugin receives either no specific value or only one value, which in some cases may not be sufficient. However, knowing the context of the event, the plugin can call back to the Bacula entry points it was passed during the loadPlugin call and get to a number of Bacula variables. (at the current time few Bacula variables are implemented, but it easily extended at a future time and as needs require).

Possible Next Steps

Go back to Plugin EntryPoints.

Go back to Bacula FD Plugin API.

Go back to Developer Guide.

handlePluginEvent(bpContext *ctx, bEvent *event, void *value)

Possible Next Steps

handlePluginEvent(bpContext ctx, bEvent event, void *value)