Camfrog Bot SDK Example
Camfrog Bot SDK Example
Camfrog Bot SDK Example
Table of Contents
1. Necessary tools
- Microsoft Visual Studio Express 2010.
- SDK library (provided with the installation package <The folder name where the bot is
installed>/dev/sdk)
- boost library (the example uses version 1.48.0 (one can download it from
http://sourceforge.net/projects/boost/files/boost/1.48.0/)
First, go to http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express
and press “Install”.
Installation process.
Installation is finished.
Second, extract the archive into the folder where the library source code will be stored (we chose
с:\libraries\boost). After extracting, we see the folder boost_1_48_0. Open this folder and run the
following command:
After the build script is executed, ready-made libraries will be located in the folder:
с:\libraries\boost\boost_1_48_0\stage\lib
In the project choice dialogue, choose “Empty Project”, specify the project name (“sample”) and the
folder where it will be stored (we chose ”c:\projects\plugin”). Press OK.
Since we need to create a plugin, the project needs to be customized so that in the end we had a
dynamic-link library sample.dll.
- Specify the paths to the source code as well as SDK and boost libraries:
- Add dependence from the plugin_sdk.lib library and the export file in which the exported
functions will be further described.
Now the project properties are set, and plugin realization can be started.
First, we need to create a class which will be responsible for initialization and creation of the plugin
graphical form.
#include <sdk/plugin_manager.h>
class plugin_manager:
public camfrog_plugin_sdk::base_plugin_mng_t
{
public:
plugin_manager(const char* plugin_id,
camfrog_plugin_sdk::plugin_bot_factory_t*);
protected:
virtual ~plugin_manager(){}
public:
virtual void on_startup();
virtual void on_stop();
The function on_statup() is called after the plugin form is initialized. One can perform additional actions
here.
The function on_stop() is called before the plugin_manager class instance is destroyed. One can
perform additional actions here.
The function add_form() is where the form will be built.
All these three functions are called automatically from the base class so it's not necessary to call them
independently.
To realize the functions, add the new file plugin_manager.cpp (please see above how to add a new file
to the project).
Add the following code to it:
#include "plugin_manager.h"
/*
include two control elements which will be used for form creation
*/
//element with static text
#include <sdk/form/control_label.h>
//element for text entry
#include <sdk/form/control_edit.h>
//--------------------------------------------------------------------------------------------------
//class constructor
plugin_manager::plugin_manager(const char* plugin_id,
camfrog_plugin_sdk::plugin_bot_factory_t* factory):
base_plugin_mng_t(plugin_id, factory)
{
}
//--------------------------------------------------------------------------------------------------
void plugin_manager::on_startup()
{
/*your code*/
}
//--------------------------------------------------------------------------------------------------
void plugin_manager::add_form(camfrog_plugin_sdk::form_cfg_t& form_cfg)
{
namespace sdk = camfrog_plugin_sdk;
The function add_form() is the most interesting here. As we can see, the form is created here.
A form with the name ”sample” is created, three elements are added to it, two of them are with static
text and one is a text field (we’ll put text into this field and display it by sending the ”/msg” command to
the bot).
The form cannot be changed when the plugin is launched.
The initializing class is created, the form is built, now it’s time to make the bot load the plugin.
In this next step, we'll show how to connect the plugin to the bot.
Create a new file, name it “sample.h” and add the following code to it:
#include "sdk/plugin_sdk.h"
class plugin_manager_interface_t;
The function cfbot_get_plugin is called when the plugin is added to the bot passing the interface we
should initialize, here we initialize the class plugin_manager. It’s not necessary to delete the class
independently, the bot will take care of it.
The function cfbot_plugininformation, here we fill in the structure CFBOT_PLUGININFORMATION in
which the unique information about the plugin is passed (the bot cannot have two plugins having similar
values of the field CFBOT_PLUGININFORMATION ).
Now let’s add realization of these functions.
Let's create a new file, name it “sample.cpp” and add the following code to it:
//class factory creates the class which will be responsible for processing the packs for the bot which will
have this plugin connected.
class plugin_bot_factory:
public camfrog_plugin_sdk::plugin_bot_factory_t
{
public:
camfrog_plugin_sdk::base_plugin_bot_t*
create_plugin_bot(camfrog_plugin_sdk::base_plugin_mng_t* mngr,
const char* bot_name, const char* work_dir)
{
plugin_bot_factory _factory;
extern "C"
{
void cfbot_get_plugin(camfrog_plugin_sdk::plugin_manager_interface_t** mng)
{
// initialization of the class plugin_manager
*mng = new plugin_manager(PLUGIN_UNIQID, &_factory);
}
strcpy_s(info->_uniq_id, 9, PLUGIN_UNIQID);
info->_version = CF_BOT_VERSION(6, 0);
info->_desired_bot_version = CF_BOT_VERSION(6, 0);
So, that’s quite a simple way we used to write bot initialization. Now we need to make these two
functions visible to the bot, and here is what we need to make:
Do you remember how we set the export.def file in the project properties? Now it’s time to create it.
Create the file export.def in any text editor, add it to the project,
LIBRARY "sample"
EXPORTS
cfbot_get_plugin
cfbot_plugininformation
Now when the bot loads our plugin, it will be able to see these two functions.
The project is compiled and we have the file sample.dll, it needs to be copied in the folder for bot
plugins <folder where the bot was installed>\plugins\.
On the ”Module Information” tab, we should see the information about the plugin.
Now we have the plugin which can be added to the bot, it has its form and data, but it doesn't do
anything.
Before we move to the seconds step, create the file defines.h and insert the following code lines into it:
//comand of plugin
#define CMD_MESSAGE "/MSG"
The next step will be to write a code which will read/record form element values, save values in a file,
run the specified command.
For this we need to create a class which will be responsible for processing the events which come from
the bot and where the main functionality of the bot will be described.
Add a new file to the project and call it plugin_bot_manager.h. Add the following code to it:
#include "sdk/plugin_bot.h"
class plugin_bot_manager:
public camfrog_plugin_sdk::base_plugin_bot_t
{
private:
std::string _message;
std::string _message_copy;
public:
plugin_bot_manager(camfrog_plugin_sdk::base_plugin_mng_t* mngr,
const char* name,
const char* work_dir);
~plugin_bot_manager();
protected:
Let’s review the last three functions: on_get_settings(), on_apply_settings() and on_process_settings().
The function on_get_settings() is called when the bot requests the form elements values (the user
opened the plugin form), we only need to fill the elements with our values.
The function on_apply_settings() is called when the user has made changes to the form and pressed the
”Apply” button, we need to save the form elements values in out variables so that we could provide the
correct values when the bot requests form values using the on_get_settings() function; after exiting this
function, all configuration parameters are automatically saved in the file.
The function on_process_settings() is called when the user makes changes to form element values, we
can read the current element values and perform some actions.
on_bot_info_request() – here the pack with commands supported by the plugin is filled in.
on_bot_show_help() – is called when the command ”/help <plugin_id>” is sent to the bot, in this
function the plugin description is filled in, for example, the unique number, short description, the
supported commands.
The image shows that the “help” command displays the plugin description which was formed in the
function on_bot_show_help().
#include "plugin_bot_manager.h"
#include "defines.h"
//--------------------------------------------------------------------------------------------------
plugin_bot_manager::plugin_bot_manager(camfrog_plugin_sdk::base_plugin_mng_t* mngr,
const char* name,
const char* work_dir):
camfrog_plugin_sdk::base_plugin_bot_t(mngr, name, work_dir)
{
}
//--------------------------------------------------------------------------------------------------
plugin_bot_manager::~plugin_bot_manager()
{
}
//--------------------------------------------------------------------------------------------------
const char* plugin_bot_manager::get_conf_file_name()
{
return CONFIG_FILENAME;
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_start()
{
/*your code*/
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::add_options(camfrog_plugin_sdk::config_file* cfg)
{
// add the parameter which will be stored in the configuration file, in our case this file will be located
here: "C:\Documents and Settings\<Windows user name>\Application Data\Camfrog
Bot\test_bot\sample.conf", and seen, we link the variable ” _message” to this parameter. Everything
that we'll save to this variable will be saved in the file CONFIG_FILENAME and loaded from it.
(*cfg).add_options()
("message",
sdk::value<std::string>(&_message).default_value(""));
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_stop()
{
/*your code*/
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_get_settings(camfrog_plugin_sdk::data_exchanger_t* data)
{
// bot requests the form data.
// we read the value from the variable ”_message” and put it
// in the form element "edit_new_text"
(*data).exchange()
("edit_new_text", &_message);
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_apply_settings(camfrog_plugin_sdk::data_exchanger_t* data)
{
// the user pressed the button ”Apply” in the form.
// we read the value from the form element "edit_new_text" and save it
// in the variable "_message"
(*data).exchange()
("edit_new_text", &_message);
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_process_settings(camfrog_plugin_sdk::data_exchanger_t* data)
{
//in this method, one can read temporary values (the user currently changing the value) of the form
elements, save them in the temporary variables and perform some actions.
// (*data).exchange()
// ("edit_new_text", &_message_copy);
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_bot_info_request(pkt_t& pkt)
{
// here a plugin data request comes
if (text.empty())
return;
}
}
Delete the plugin from the bot, replace it with a new one (which we have just built).
Connect the new plugin.
Run Camfrog Client.
Add the bot to the list.
If you now try to send the command ”/help” to the bot in the bot IM window,
© 2013 Camshare Inc. Page 28
Camfrog Bot 6.0
In the form of the imcontrol.dll plugin, add the user nickname which will be allowed to call plugin
commands for the bot.
Now, when the user nickname which will be allowed to run commands for the bot is added, we do the
following:
Run the command ”/modules”, it will display the list of plugins of the current bot:
We see that the plugin supports just one command “/msg”. If we send it to the bot, it will return the text
we entered in the entry field in the form of our plugin.
Don’t forget to press the button ”Apply” when you add the text into this field, otherwise the text won’t
be saved.
We can also see that the text that we entered into the entry field on the plugin form was saved in the
configuration file.
"C:\Documents and Settings\< name of current user>\Application Data\Camfrog
Bot\test_bot\sample.conf" as:
5. Event processing
For event processing, it's enough to specify the necessary event and define which function will process
it.
The user will send the text to the bot (the BOT_EVENT_IM event) and our plugin will read this text, add
the inscription “ (from <name of bot>)” in the end, and send it back.
Open our ”sample” project. Add in the file ”plugin_bot_manager.h” the following code:
void on_im_message(pkt_t &pkt); //the function which will describe the event
// as we can see, we added the event BOT_EVENT_IM in the event map and defined the function in
which this event will be processed.
BEGIN_EVENT_MAP(plugin_bot_manager, base_plugin_bot_t)
ON_IM_EVENT(BOT_EVENT_IM, on_im_message)
END_EVENT_MAP()
// we form the string which will be sent back text = text + std::string("(from ") +
std::string(get_name())+ std::string(" )");
// we create that reply pack in which we put the name (recipient) and text (we would like to send)
pkt_t pkt_v(PLUGIN_EVENT_IM);
pkt_v << pkt_value(0x01, nickname)
<< pkt_value(0x02, text.c_str() );
//we send the pack
notify_data_event(get_name(), pkt_v.data().c_str(), (int)pkt_v.data().size());
}
Delete the old plugin from the bot, replace it with a new one (which we have just built).
Connect the new plugin.
Run Camfrog Client.
Enter any text in the bot IM window (for example, ”Hello Bot”)and send it.
In the result we get:
Other events available to the plugin are described in the document "Camfrog Bot SDK.chm".