Notify API How-To

This document will explain how to use the notify API to enable your libpurple plugins to notify the user of events or other pertinent information. Again we will assume that you have completed the Basic C Plugin Howto. We'll also continue to assume that you're using Pidgin 2.0.2 for these How-To documents as described there.

1. About the Notify API
2. Using This Part of the Notify API
3. Writing the Example Plugin
4. Compiling, Installing, and Testing the Plugin
5. Beyond the Notify API

About the Notify API

The notify API is a rather large API, which this plugin will not cover in its entirety. The portions that we cover here allow your plugin to make the UI notify the user of some event or other noteworthy information. Most of the functions that we'll explore here present dialogs in Pidgin, but one causes Pidgin to open a URI in the appropriate application.

Surely by now, some readers are wondering why this How-To is leaving out sections of the notify API. The purpose of this document is to introduce you to the basic toolset and allow you the opportunity to grow on your own, learning the API as you need it to do more advanced plugin development. Additional How-To documents may appear in the future to cover the other sections of the notify API, as well.

Using This Part of the Notify API

If you read the API documentation for notify.h, you will see that most of the functions we explore here call for some common arguments. Here is the list and their explanations:

• handle - a UI-specific or plugin-specific handle for use by the notify API. Generally, you will feed this argument the PurplePlugin * for your plugin.
• title - the title for the notification. The handling of this may vary depending on a number of factors.
• primary - the primary text of the notification. This text generally appears as larger and bold-faced when compared to the secondary text. You will generally make this a concise message, such as "Error reading file!"
• secondary - the secondary text of the notification. This text generally appears as smaller and plain when compared to the primary text. You will generally make this a more detailed message, such as "Couldn't open file /path/to/foo for reading: No such file or directory."

Writing the Example Plugin

For this document we're going to have yet another new example plugin. This one will be called notify_example.c and will also live in ~/development/pidgin-2.0.2/libpurple/plugins. By now, the entirety of the plugin facilities used here, save for the purple_notify_* function calls, should be familiar to you, so we'll skip the fanfare and get to the meat of the plugin:

#include <glib.h>

# define PURPLE_PLUGINS

#define PLUGIN_ID "core-notifyexample"
#define PLUGIN_AUTHOR "John Bailey <rekkanoryo@cpw.pidgin.im>"
#define VERSION "1.0"

#include <notify.h>
#include <plugin.h>
#include <version.h>

static PurplePlugin *notify_example = NULL;

/* The next four functions and the calls within them should cause dialog boxes to appear
 * when you select the plugin action from the Tools->Notify Example menu */
static void
notify_error_cb(PurplePluginAction *action)
{
    purple_notify_error(notify_example, "Test Notification", "Test Notification",
        "This is a test error notification");
}

static void
notify_info_cb(PurplePluginAction *action)
{
    purple_notify_info(notify_example, "Test Notification", "Test Notification",
        "This is a test informative notification");
}

static void
notify_warn_cb(PurplePluginAction *action)
{
    purple_notify_warning(notify_example, "Test Notification", "Test Notification",
        "This is a test warning notification");
}

static void
notify_format_cb(PurplePluginAction *action)
{
    purple_notify_formatted(notify_example, "Test Notification", "Test Notification",
        "Test Notification",
        "<I>This is a test notification with formatted text.</I>", NULL, NULL);
}

static void
notify_uri_cb(PurplePluginAction *action)
{
    /* This one should open your web browser of choice. */
    purple_notify_uri(notify_example, "http://www.pidgin.im/");
}

static GList *
plugin_actions(PurplePlugin *plugin, gpointer context)
{
    GList *actions = NULL;

    /* Here we take advantage of return values to avoid the need for a temp variable */
    actions = g_list_prepend(actions,
        purple_plugin_action_new("Show Error Notification", notify_error_cb));

    actions = g_list_prepend(actions,
        purple_plugin_action_new("Show Info Notification", notify_info_cb));

    actions = g_list_prepend(actions,
        purple_plugin_action_new("Show Warning Notification", notify_warn_cb));

    actions = g_list_prepend(actions,
        purple_plugin_action_new("Show Formatted Notification", notify_format_cb));

    actions = g_list_prepend(actions,
        purple_plugin_action_new("Show URI Notification", notify_uri_cb));

    return g_list_reverse(actions);
}

static gboolean
plugin_load(PurplePlugin *plugin)
{
    notify_example = plugin;

    return TRUE;
}

static PurplePluginInfo info = {
    PURPLE_PLUGIN_MAGIC,        /* magic number */
    PURPLE_MAJOR_VERSION,       /* purple major */
    PURPLE_MINOR_VERSION,       /* purple minor */
    PURPLE_PLUGIN_STANDARD,     /* plugin type */
    NULL,                       /* UI requirement */
    0,                          /* flags */
    NULL,                       /* dependencies */
    PURPLE_PRIORITY_DEFAULT,    /* priority */

    PLUGIN_ID,                  /* id */
    "Notify API Example",       /* name */
    VERSION,                    /* version */
    "Notify API Example",       /* summary */
    "Notify API Example",       /* description */
    PLUGIN_AUTHOR,              /* author */
    "http://pidgin.im",         /* homepage */

    plugin_load,                /* load */
    NULL,                       /* unload */
    NULL,                       /* destroy */

    NULL,                       /* ui info */
    NULL,                       /* extra info */
    NULL,                       /* prefs info */
    plugin_actions,             /* actions */
    NULL,                       /* reserved */
    NULL,                       /* reserved */
    NULL,                       /* reserved */
    NULL                        /* reserved */
};

static void
init_plugin(PurplePlugin *plugin)
{
}

PURPLE_INIT_PLUGIN(notifyexample, init_plugin, info)

Compiling, Installing, and Testing the Plugin

As before, run make notify_example.so (make -f Makefile.mingw notify_example.dll for you Windows types) to build the plugin. Copy the resulting notify_example.so to ~/.purple/plugins, or copy the resulting notify_example.dll to %APPDATA%\.purple\plugins.

Once this is done, load the plugin in Pidgin, then go to Tools->Notify Example and look one by one at the dialogs resulting from selecting each action. Dismiss them whenever you please.

Beyond the Notify API

The notify API provides a basic notification framework for plugins, which can be an extremely valuable resource to plugin authors. The other areas we didn't cover here include much of the true power of the notify API, but we will leave those as an area for your exploration at least for now. This document is done, but there are still others in the C Plugin How-To for you to explore!