This document describes how to create your own plugin for abrt.

Although a base abstract class CPlugin exists, you can't inherit
directly from it. You must use one of the four subclasses,
depending on what you want your plugin to do.

The subclasses are:
    * Action plugin (CAction)
    * Analyzer plugin (CAnalyzer)
    * Reporter plugin (CReporter)
    * Database plugin (CDatabase)

Each of them requires you to override a different set of methods.

The pDebugDumpDir parameter is very common: it specifies the directory
that is created to gather information of this specific crash.
The files that were created when the application crashed (such as core dumps)
are all stored here. In addition, the plugins can write
their output files there, if any.

Plugin types in detail:


Analyzer Plugin
---------------
Crashes differ, depending on where they occur, for example crashes
in the kernel differ from crashes in userspace binaries, which differ
from crashes in python scripts. Therefore, there is a plugin
for each type of application that you want abrt to handle.

You have to override these methods:

virtual std::string GetLocalUUID(const char *pDebugDumpPath);
- This method is invoked immediately after crash is detected
  and its data is saved by the corresponding hook.
  It needs to compute an unique hash (UUID) of the crash.
  When a crash occurs and abrt finds an earlier crash with the same
  UUID, new crash is discarded as a duplicate, it doesn't show up
  in abrt's crash list, but instead a crash count for the earlier
  crash is incremented.

virtual void CreateReport(const char *pDebugDumpDir, int force)
- This method is called when user wants to report a crash
  ([Reoprt] button in GUI, etc). Analyzer can perform additional,
  more CPU/disk intensive, or interactive processing at this point.
  For example, CCpp plugin's CreateReport() processes coredump file,
  produces a textual backtrace, and saves it to crash dump directory.

virtual std::string GetGlobalUUID(const char *pDebugDumpPath);
- This method computes a "duplicate hash" which is used search for
  duplicates in remote bug databases such as Bugzilla. They are
  "less unique" than LocalUUIDs: ideally, the same crash
  on different architecture or with slightly different backtrace
  will still have the same GlobalUUID.
  [TODO: renaming it to DUPHASH]


Action Plugin
-------------
This type of plugin is useful when you need some action to be performed.
Action plugins can be invoked in three ways:

* Immediately when a crash is encountered (using ActionsAndReporters = ...
  directive in abrt.conf). These action plugins are run on every crash
  (regardless of crash type).

* After Analyzer plugin processed a crash (by specifying plugin in
  [AnalyzerActionsAndReporters] section, for example: "CCpp = AnActionPlugin").
  In this case, action plugin's Run() method will be run after analyzer
  plugin's CreateReport() and GetGlobalUUID() methods have finished.

* If you need some action to be performed periodically ([Cron] section
  in the same file).

You have to override one method:

virtual void Run(const char *dir, const char *args);

The first argument is a directory that contains the current debug
dump, or all debug dumps for periodic actions.
The second argument is a string with arguments (specified in config file).


Database Plugin
---------------
This plugin is used to store the metadata about the crash. The metadata
has to be in a database, to distinguish whether the current crash is or
is not the same as some crash before. The database can be local, or in
some centralized location on the network.

You have to override these methods:
virtual void Connect();
virtual void DisConnect();
- connect and disconnect from the database

virtual void Insert(const std::string& pUUID,
                    const std::string& pUID,
                    const std::string& pDebugDumpPath,
                    const std::string& pTime);
- insert an entry into the database: you use both UID (user ID) and UUID
  (ID of the crash)

virtual void Delete(const std::string& pUUID, const std::string& pUID);
- delete an entry

virtual void SetReported(const std::string& pUUID, const std::string& pUID);
- insert information into the database to say that this bug was already
  reported (so for example the report plugins won't run several times
  for the same bug)

virtual const vector_database_rows_t GetUIDData(const std::string& pUID);
- get database rows for the specified user ID

virtual const database_row_t GetUUIDData(const std::string& pUUID, const
 std::string& pUID);
- get a database row for the specified user ID and UUID


The macro PLUGIN_INFO
---------------------
Use the macro PLUGIN_INFO in the *.cpp file of your plugin so that your
subclass will be properly registered and treated as a plugin.
This sets up all the lower-level and administrative details to fit your
class into the plugin infrastructure. The syntax is:

PLUGIN_INFO(type, plugin_class, name, version, description, email, www)
- "type" is one of ANALYZER, ACTION, REPORTER, or DATABASE
- "plugin_class" is the identifier of the class
- "name" is a string with the name of the plugin
- "version" is a string with the version of the plugin
- "description" is a string with the summary of what the plugin does
- "email" and "www" are strings with the contact info for the author

For example:
PLUGIN_INFO(REPORTER,
            CMailx,
            "Mailx",
            "0.0.1",
            "Sends an email with a report via mailx command",
            "zprikryl@redhat.com",
            "https://fedorahosted.org/crash-catcher/wiki");