Code-Beispiel

Kommando-Plugin für libpurple (Pidgin)

Lizenz:	Erster Autor:	Letzte Bearbeitung:
GPLv3	TJF	17.01.2012

Dieses Beispiel betrifft ein Plugin für die Verwendung unter LibPurple. Der Code kann unter win32 oder LINUX mit der Option -dylib kompiliert und dann z. B. in Pidgin als Plugin verwendet werden. Doch alles der Reihe nach:

libpurple ist eine in C geschrieben Bibliothek, welche die Basisfunktionen für einen Multi-Protokoll-Client bereitstellt. libpurple (früher libgaim) wird zusammen mit dem Programm Pidgin entwickelt. Beide sind unter der GPLv2 lizensiert und damit frei nutzbar, und zwar unter win32 und LINUX Betriebssystemen (und auch unter MacOSX). Mit diesem Multi-Protokoll-Client ist es möglich, verschiedene Instant-Messenger-Dienste zu nutzen. Über ein in FreeBasic geschriebenes libpurple-Plugin hat man also Zugriff auf eine ganze Reihe von Message-Protokollen am Internet.

Dieses Beispiel ist der Dokumentation von Pidgin entnommen und ist aus diesem C-Code in FreeBasic-Quelltext übersetzt. Als Plugin eingesetzt stellt es zwei neue Befehle bereit, welche - wenn sie in einem Chat-Fenster eingegeben werden - ein Informationsfenster darstellen oder einen Eintrag in den Log vornehmen.

Der folgende Quelltext sollte unter dem Namen "pidgin-cmd.bas" in einen neuen Projektordner gespeichert werden. Der Quelltext verwendet die libpurple-Header, welche (mit der gesamten Ordnerstruktur) entweder in den Projektordner (zum Kurztest) oder in den "FreeBasic/inc[lude]" Ordner (zur dauerhaften Verwendung) kopiert werden.

' This is file

'   pidgin-cmd.bas

' (C) GPLv3 by

'   Thomas{dot]Freiherr[at]gmx[dot}net

' Translated from C source

'   http://developer.pidgin.im/wiki/CHowTo/CommandAPIHowTo

' kompilieren:

'   fbc -exx -w all -dylib pidgin-cmd.bas



'/*

 '* Command Example Plugin

 '*

 '* Copyright (C) 2009, Hamilton Turner <hamiltont@gmail.com>

 '*

 '* This program is free software; you can redistribute it and/or

 '* modify it under the terms of the GNU General Public License as

 '* published by the Free Software Foundation; either version 2 of the

 '* License, or (at your option) any later version.

 '*

 '* This program is distributed in the hope that it will be useful, but

 '* WITHOUT ANY WARRANTY; without even the implied warranty of

 '* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 '* General Public License for more details.

 '*

 '* You should have received a copy of the GNU General Public License

 '* along with this program; if not, write to the Free Software

 '* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA

 '* 02111-1301, USA.

 '*

 '*/



'/* This is the required definition of PURPLE_PLUGINS as required for a plugin,

 '* but we protect it with an #ifndef because config.h may define it for us

 '* already and this would cause an unneeded compiler warning. */

'#IFNDEF PURPLE_PLUGINS

'# DEFINE PURPLE_PLUGINS

'#ENDIF

' deprecated since 2.3



#INCLUDE ONCE "glib.bi"



'/* Here we're including the necessary libpurple headers for this plugin.  Note

 '* that we're including them in alphabetical order.  This isn't necessary but

 '* we do this throughout our source for consistency. */

'#INCLUDE ONCE "libpurple/mediamanager.bi"

'#INCLUDE ONCE "libpurple/cmds.bi"

'#INCLUDE ONCE "libpurple/debug.bi"

'#INCLUDE ONCE "libpurple/notify.bi"

'#INCLUDE ONCE "libpurple/plugin.bi"

'#INCLUDE ONCE "libpurple/version.bi"

#INCLUDE ONCE "libpurple/purple.bi" ' new since 2.3



#IFDEF HAVE_CONFIG_H

# INCLUDE <config.h>

#ENDIF



'/* It's more convenient to type PLUGIN_ID all the time than it is to type

 '* "core-commandexample", so define this convenience macro. */

#DEFINE PLUGIN_ID "core-commandexample"



'/* Common practice in third-party plugins is to define convenience macros for

 '* many of the fields of the plugin info struct, so we'll do that for the

 '* purposes of demonstration. */

#DEFINE PLUGIN_AUTHOR "Hamilton Turner <hamiltont@gmail.com>"



'/**

 '* Initialized in the plugin_load() method, this allows us to keep a handle to

 '* ourself. Such a handle is needed to register for commands, so that libpurple

 '* has a handle to the plugin that registered for the command

 '*/

STATIC SHARED AS PurplePlugin PTR command_example = NULL



'/**

 '* Used to hold a handle to the commands we register. Holding this handle

 '* allows us to unregister the commands at a later time.

 '*/

STATIC SHARED AS PurpleCmdId log_command_id, notify_command_id



'/**

 '* The callback function for our /log command. This function simply prints

 '* whatever was entered as the argument to the debug command into the debug

 '* log.

 '*

 '* @param conv The conversation that the command occurred in

 '* @param cmd The exact command that was entered

 '* @param args The args that were passed with the command

 '* @param error ?Any errors that occurred?

 '* @param data Any special user-defined data that was assigned during

 '*             cmd_register

 '*/

FUNCTION log_cb CDECL( _

  BYVAL conv AS PurpleConversation PTR, _

  BYVAL cmd AS CONST gchar PTR, _

  BYVAL args AS gchar PTR PTR, _

  BYVAL error_ AS gchar PTR PTR, _

  BYVAL data_ AS ANY PTR) AS PurpleCmdRet STATIC



  purple_debug_misc(PLUGIN_ID, !"log_cb called\n")

  purple_debug_misc(PLUGIN_ID, !"message = %s\n", args[0])



  RETURN PURPLE_CMD_RET_OK

END FUNCTION



'/**

 '* The callback function for our /notify command. This function simply pops up

 '* a notification with the word entered as the argument to the command

 '*

 '* @param conv The conversation that the command occurred in

 '* @param cmd The exact command that was entered

 '* @param args The args that were passed with the command

 '* @param error ?Any errors that occurred?

 '* @param data Any special user-defined data that was assigned during

 '*             cmd_register

 '*/

FUNCTION notify_cb CDECL( _

  BYVAL conv AS PurpleConversation PTR, _

  BYVAL cmd AS CONST gchar PTR, _

  BYVAL args AS gchar PTR PTR, _

  BYVAL error_ AS gchar PTR PTR, _

  BYVAL data_ AS ANY PTR) AS PurpleCmdRet STATIC



  purple_notify_info(command_example, _

                     "Notify Notification Title", _

                     "Notify Notification Primary Text", _

                     args[0]) '   /* Secondary text is the word entered */



  RETURN PURPLE_CMD_RET_OK

END FUNCTION



'/**

 '* Because we added a pointer to this function in the load section of our

 '* PurplePluginInfo, this function is called when the plugin loads.

 '* Here we're using it to show off the capabilities of the

 '* command API by registering a few commands. We return TRUE to tell libpurple

 '* it's safe to continue loading.

 '*/

FUNCTION plugin_load CDECL( _

  BYVAL plugin AS PurplePlugin PTR) AS gboolean STATIC

  '// Declare all vars up front. Avoids warnings on some compilers



  DIM AS gchar PTR log_help = NULL

  DIM AS gchar PTR notify_help = NULL



  '// Save a handle to ourself for later

  command_example = plugin



  '// Help message for log command, in the correct format

  log_help = @"log <log message here>:  Prints a message to the debug log."



  '// Register a command to allow a user to enter /log some message and have

  '// that message stored to the log. This command runs with default priority,

  '// can only be used in a standard chat message, not while in group chat

  '// mode

  log_command_id = purple_cmd_register _

    ("log", _                         /* COMMAND NAME */

     "s", _                           /* COMMAND argument FORMAT */

     PURPLE_CMD_P_DEFAULT, _          /* COMMAND priority flags */

     PURPLE_CMD_FLAG_IM, _            /* COMMAND usage flags */

     PLUGIN_ID, _                     /* Plugin ID */

     @log_cb, _                       /* NAME of the callback FUNCTION */

     log_help, _                      /* Help message */

     NULL _                           /* ANY special user-defined DATA */

     )





  '// Help message for notify command, in the correct format

  notify_help = @"notify <notify word here>:  Pops up a notification with the word you enter."



  '// Register a command to allow a user to enter /notify some word and have

  '// that word notified back to them. This command runs with high priority,

  '// and can be used in both group and standard chat messages

  notify_command_id = purple_cmd_register _

    ("notify", _                      /* COMMAND NAME */

     "w", _                           /* COMMAND argument FORMAT */

     PURPLE_CMD_P_HIGH, _             /* COMMAND priority flags */

     PURPLE_CMD_FLAG_IM OR _

       PURPLE_CMD_FLAG_CHAT, _        /* COMMAND usage flags */

     PLUGIN_ID, _                     /* Plugin ID */

     @notify_cb, _                    /* Callback FUNCTION */

     notify_help, _                   /* Help message */

     NULL _                           /* ANY special user-defined DATA */

     )





  '/* Just return true to tell libpurple to finish loading. */

  RETURN TRUE

END FUNCTION



'/**

 '* Because we added a pointer to this function in the unload section of our

 '* PurplePluginInfo, this function is called when the plugin unloads.

 '* Here we're using it to show off the capabilities of the

 '* command API by unregistering a few commands. We return TRUE to tell libpurple

 '* it's safe to continue unloading.

 '*/

FUNCTION plugin_unload CDECL( _

  BYVAL plugin AS PurplePlugin PTR) AS gboolean STATIC

  purple_cmd_unregister(log_command_id)

  purple_cmd_unregister(notify_command_id)



  '/* Just return true to tell libpurple to finish unloading. */

  RETURN TRUE

END FUNCTION



STATIC SHARED AS PurplePluginInfo info = TYPE<PurplePluginInfo>( _

    PURPLE_PLUGIN_MAGIC, _

    PURPLE_MAJOR_VERSION, _

    PURPLE_MINOR_VERSION, _

    PURPLE_PLUGIN_STANDARD, _

    NULL, _

    0, _

    NULL, _

    PURPLE_PRIORITY_DEFAULT, _

    @PLUGIN_ID, _

    @!"Command API Example", _

    @!"1.0", _

    @!"Command API Example", _

    @!"Command API Example", _

    @PLUGIN_AUTHOR, _

    @!"http://pidgin.im", _

    @plugin_load(), _

    @plugin_unload(), _

    NULL, _

    NULL, _

    NULL, _

    NULL, _

    NULL, _

    NULL, _

    NULL, _

    NULL, _

    NULL _

)



SUB init_plugin(BYVAL plugin AS PurplePlugin PTR)

END SUB



PURPLE_INIT_PLUGIN(hello_world, init_plugin, info)

FB Plugin aufgelistet in Pidgin

Der Quelltext wird als Bibliothek kompiliert mit dem Befehl

fbc -exx -w all -dylib pidgin-cmd.bas

wodurch eine neue Datei mit dem Namen "libpidgin-cmd.so" (bzw. "libpidgin-cmd.dll" auf win32) entsteht. Diese Datei wird in den plugin-Ordner der Pidgin Installation verschoben (und vorteilhafterweise umbenannt in "pidgin-cmd.*"). Unter Debian ist das der Ordner "~/.purple/plugins" für lokale Verwendung bzw. "./usr/lib/purple-2" für globale Verwendung.

Beim nächsten Start von Pidgin sollte dann bei Aufruf der Menüfunktion "Werkzeuge->Plugins" unser Plugin in der Liste zu finden sein, vgl. Bild oben. Wenn dieses Plugin "Aktiv" geschaltet wird, dann sind zwei neue Kommandos in allen Chat-Fenstern verfügbar:

/log bewirkt, dass der folgende Text in das "Hilfe->Debug-Fenster" eingetragen wird (ergänzt durch eine Ankündigungszeile). Beispiel: /log Dies ist eine Debug-Meldung! erzeugt den Eintrag

(16:29:56) core-commandexample: log_cb called

(16:29:56) core-commandexample: message = Dies ist eine Debug-Meldung!

Bildschirmnachricht in Pidgin

/notify öffnet ein Fenster mit einer Nachricht an den Benutzer und wartet auf dessen Bestätigung. Beispiel /notify www.freebasic-portal.de öffnet das rechts abgebildete Fenster. Bei diesem Befehl ist nur ein Parameter erlaubt. Enthält die Zeichenkette nach dem Befehl Leerzeichen, so führt dies zu einer Fehlermeldung (im Chat-Fenster).

Weitere Beispiele und Informationen zur Verwendung der libpurple-API sind auf der Pidgin-Webseite (en) zu finden. Plugins können sowohl für Textnachrichten als auch für Audio- und Video-Dienste eingesetzt werden, bzw. Dateien zwischen den Verbindungsteilnehmern austauschen.

English

See English forum.

Zusätzliche Informationen und Funktionen

Das Code-Beispiel wurde am 12.01.2012 von TJF angelegt.
Die aktuellste Version wurde am 17.01.2012 von TJF gespeichert.

Bearbeiten

Versionen