Sei sulla pagina 1di 35

Plugin creation using

SDK in Microsoft Visual


Studio Express 2010

© 2012 Camshare Inc.


Camfrog Bot 6.0

Table of Contents

1. Necessary tools ............................................................................................................................3


2. Installation of Microsoft Visual Studio Express 2010 ..................................................................3
3. Boost library building...................................................................................................................8
4. Project creation and customization in Microsoft Visual Studio Express 2010 ............................8
5. Event processing ........................................................................................................................33

© 2013 Camshare Inc. Page 2


Camfrog Bot 6.0

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/)

2. Installation of Microsoft Visual Studio Express 2010


You can skip this section if you already know how to install this product.

First, go to http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express
and press “Install”.

© 2013 Camshare Inc. Page 3


Camfrog Bot 6.0

Second, press the marked button.

The installation script vc_web.exe will be downloaded to your computer.

Next, run this script.

© 2013 Camshare Inc. Page 4


Camfrog Bot 6.0

Installation of Microsoft Visual Studio Express 2010

© 2013 Camshare Inc. Page 5


Camfrog Bot 6.0

© 2013 Camshare Inc. Page 6


Camfrog Bot 6.0

Installation process.

Installation is finished.

© 2013 Camshare Inc. Page 7


Camfrog Bot 6.0

3. Boost library building


You can skip this section if you already know how this library is built.

First, go to http://sourceforge.net/projects/boost/files/boost/1.48.0/. Choose the archive and download


it.

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:

с:\libraries\boost\boost_1_48_0\ bjam toolset=msvc link=static threading=multi runtime-link=static --


build-type=complete

After the build script is executed, ready-made libraries will be located in the folder:

с:\libraries\boost\boost_1_48_0\stage\lib

4. Project creation and customization in Microsoft Visual Studio Express


2010

First, launch Microsoft VS Express 2010.

© 2013 Camshare Inc. Page 8


Camfrog Bot 6.0

Second, create a new project.

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.

© 2013 Camshare Inc. Page 9


Camfrog Bot 6.0

A new project is created.

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.

© 2013 Camshare Inc. Page 10


Camfrog Bot 6.0

For this, open project properties.

Then, make the following changes in the project properties dialogue.

© 2013 Camshare Inc. Page 11


Camfrog Bot 6.0

- Specify that it will be a .dll library.

© 2013 Camshare Inc. Page 12


Camfrog Bot 6.0

- Specify the paths to the source code as well as SDK and boost libraries:

Include Directories : C:\Program Files\Camfrog\Camfrog Bot\dev\sdk\; C:\libraries\boost_1_48_0\;

Library Directories : C:\Program Files\Camfrog\Camfrog Bot\dev\sdk\lib\ms\2010_Express\;


C:\libraries\boost_1_48_0\stage\lib;

© 2013 Camshare Inc. Page 13


Camfrog Bot 6.0

- 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.

© 2013 Camshare Inc. Page 14


Camfrog Bot 6.0

First, we need to create a class which will be responsible for initialization and creation of the plugin
graphical form.

© 2013 Camshare Inc. Page 15


Camfrog Bot 6.0

Let’s call it plugin_manager.h

Now we’ll add description of the new class plugin_manager.

#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();

virtual void add_form(camfrog_plugin_sdk::form_cfg_t& form_cfg);


};

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.

© 2013 Camshare Inc. Page 16


Camfrog Bot 6.0

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;

//create a form with the name "sample"


sdk::form_t main_frm("sample");

//add elements to the form


main_frm.add_control()
(&sdk::ctrl_label("label5", sdk::rect_t(20, 120, 200, 20), "This message will appear, when you type
/text command"))
(&sdk::ctrl_label("label2", sdk::rect_t(20, 160, 60, 20), "Enter text"))
(&sdk::ctrl_edit("edit_new_text", sdk::rect_t(70, 160, 150, 22)));
//add the form to the class which stores the form configuration
form_cfg.add_form()(main_frm);
}
//--------------------------------------------------------------------------------------------------
void bot_manager::on_stop()
{
/*your code*/
}

© 2013 Camshare Inc. Page 17


Camfrog Bot 6.0

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;

void __cdecl cfbot_get_plugin(camfrog_plugin_sdk::plugin_manager_interface_t** mng);


void __cdecl cfbot_plugininformation(CFBOT_PLUGININFORMATION *info);

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:

#include <string.h> // needed for the function strcpy_s

#include "plugin_manager.h" // description of the initialization class


//#include "plugin_bot_manager.h"// description of the class which will be responsible for working with
the bot the plugin is connected to, it will be created later

#include "sdk/description.h" // description of the structure CFBOT_PLUGININFORMATION and macros


#include "sdk/plugin_bot_factory.h" // class factory

#define PLUGIN_UNIQID "CSLLCSPL" // unique plugin name

//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)
{

© 2013 Camshare Inc. Page 18


Camfrog Bot 6.0

return NULL;// nothing is created here at the moment


}
};

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);
}

void cfbot_plugininformation(CFBOT_PLUGININFORMATION *info)


{
// we fill in information about the plugin

strcpy_s(info->_uniq_id, 9, PLUGIN_UNIQID);
info->_version = CF_BOT_VERSION(6, 0);
info->_desired_bot_version = CF_BOT_VERSION(6, 0);

strcpy_s(info->_description, 512, "Sample plugin");


strcpy_s(info->_authors, 512, "Sample plugin");
strcpy_s(info->_email, 512, "my email");
strcpy_s(info->_http, 512, "http://my.site.com");
}
};

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,

© 2013 Camshare Inc. Page 19


Camfrog Bot 6.0

which should look like this:

and add the following code to it:

LIBRARY "sample"
EXPORTS
cfbot_get_plugin
cfbot_plugininformation

© 2013 Camshare Inc. Page 20


Camfrog Bot 6.0

Now when the bot loads our plugin, it will be able to see these two functions.

Choose in the menu Debug->Build Solution or just press the F7 button.

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\.

Let’s try to connect our plugin to the bot.


Launch the bot.
Log in to the chat room.
Press the button “Add Module”, find our plugin “sample.dll” in the list and press ”OK”.
The result should be:

On the “Module Settings” tab, we should see the form we created.

© 2013 Camshare Inc. Page 21


Camfrog Bot 6.0

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:

//unique name of the plugin


#define PLUGIN_UNIQID "MYPLUGIN"
// short description of the plugin
#define INFO_DESCRIPTION "\"Sample \" plugin"

//name of the configuration file file


#define CONFIG_FILENAME "sample.conf"

//comand of plugin
#define CMD_MESSAGE "/MSG"

//help of plugin commands


#define MSG_HEAD "\t\tSample plugin commands\n"
#define MSG_MESSAGE_HELP "/msg - view message of plugin"

© 2013 Camshare Inc. Page 22


Camfrog Bot 6.0

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();

virtual void on_start();

virtual void add_options(camfrog_plugin_sdk::config_file* cfg);


virtual void on_stop();

virtual const char* get_conf_file_name();

protected:

void on_bot_info_request(pkt_t& pkt);


void on_bot_show_help(pkt_t& pkt);
void on_bot_process_command(pkt_t& pkt);

void on_get_settings(camfrog_plugin_sdk::data_exchanger_t* data);


void on_apply_settings(camfrog_plugin_sdk::data_exchanger_t* data);
void on_process_settings(camfrog_plugin_sdk::data_exchanger_t* data);
};

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.

© 2013 Camshare Inc. Page 23


Camfrog Bot 6.0

Now let’s review the rest of the functions.


on_start() – is called when the plugin loaded configuration parameters from the file.
on_stop() – is called before the plugin_bot_manager instance class is destroyed, for example, if the
plugin was disconnected from the bot.
add_options() – in this function one can set configuration parameters and link variables to them , which
will store values of these parameters; they will be automatically saved and loaded from the
configuration file.
get_conf_file_name() – here we should specify the name of the configuration file where the necessary
parameters will be saved, for example, form elements values.

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().

on_bot_process_command() – here the commands supported by the plugin are processed.


The picture shows that the ”/msg” command sends to the user the text which was created in the
function on_bot_process_command() .

© 2013 Camshare Inc. Page 24


Camfrog Bot 6.0

Now let’s describe all these functions.


Add a new file to the project, call it plugin_bot_manager.cpp and add the following code to it:

#include "plugin_bot_manager.h"
#include "defines.h"

namespace sdk = camfrog_plugin_sdk;

//--------------------------------------------------------------------------------------------------
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)

© 2013 Camshare Inc. Page 25


Camfrog Bot 6.0

{
// 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

std::string sender = std::string(pkt[0x01]); // the requester

// we form the pack BB_MODULE_INFO_RESPONSE with the bot data


pkt_t pkt_module_v(BB_MODULE_INFO_RESPONSE);

© 2013 Camshare Inc. Page 26


Camfrog Bot 6.0

pkt_module_v << pkt_value (0x01, PLUGIN_UNIQID)// unique plugin name


<< pkt_value (0x02, INFO_DESCRIPTION)// short plugin description
<< pkt_value (0x03, CMD_MESSAGE);//the command supported by the plugin ( there can be
several commands)

// we form the reply to the requester


pkt_t pkt_v(PLUGIN_BOT_2_BOT);
pkt_v << pkt_value(0x01, sender.c_str())
<< pkt_value(0x02, pkt_module_v.data());

//we send the reply


notify_data_event(get_name(),
pkt_v.data().c_str(),
(int)pkt_v.data().size());
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_bot_show_help(pkt_t& pkt)
{
// a request about this plugin via the ”/help” command
std::string nick = std::string(pkt[0x01]); // the requester
std::string text = std::string(pkt[0x02]);

if (text.empty())
return;

//we form the string which will be shown to the user


std::string msg = std::string(MSG_HEAD)
+ std::string("\n")
+ std::string(MSG_MESSAGE_HELP);

//we create the IM message pack


pkt_t pkt_v(PLUGIN_EVENT_IM);
pkt_v << pkt_value(0x01, nick)
<< pkt_value(0x02, msg);

//we send the pack


notify_data_event(get_name(), pkt_v.data().c_str(), (int)pkt_v.data().size());
}
//--------------------------------------------------------------------------------------------------
void plugin_bot_manager::on_bot_process_command(pkt_t& pkt)
{
std::string nick = std::string(pkt[0x01]);//the command sender (user nickname)
std::string command = std::string(pkt[0x02]); //the command
std::string text = std::string(pkt[0x03]);// the command parameters (if the command is without
parameters, then the command itself)

if (strcmp(CMD_MESSAGE, command.c_str()) == 0)//if the plugin supports this command


{
pkt_t pkt_v(PLUGIN_EVENT_IM);
pkt_v << pkt_value(0x01, nick)
<< pkt_value(0x02, _message);
notify_data_event(get_name(), pkt_v.data().c_str(), (int)pkt_v.data().size());

© 2013 Camshare Inc. Page 27


Camfrog Bot 6.0

}
}

Our new class plugin_bot_manager needs to be connected to start working.


Open the file sample.cpp and add the following code to it:
Include the class description:

Add the class instance to our factory:

Choose in the menu Debug->Build Solution or just press F7.

The build was successful.

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

you won’t receive a reply.


We need the plugin imcontrol.dll which will help us do that.
Switch to the bot window.
Add the plugin imcontrol.dll (provided with the installation package) using the ”Add Module” button.

In the form of the imcontrol.dll plugin, add the user nickname which will be allowed to call plugin
commands for the bot.

© 2013 Camshare Inc. Page 29


Camfrog Bot 6.0

If we don’t do this, calling any command will result in the following:

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:

© 2013 Camshare Inc. Page 30


Camfrog Bot 6.0

In the received list, we see our plugin ”MYPLUGIN” .


In order to know which commands are supported by this bot, one just needs to send the command
”/help MYPLUGIN”.

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.

© 2013 Camshare Inc. Page 31


Camfrog Bot 6.0

Don’t forget to press the button ”Apply” when you add the text into this field, otherwise the text won’t
be saved.

Try running the command ”/msg”.


Here is the result.

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:

© 2013 Camshare Inc. Page 32


Camfrog Bot 6.0

This parameter was added in the function add_options()

5. Event processing
For event processing, it's enough to specify the necessary event and define which function will process
it.

Let’s create an example which will work as follows:

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

DECLARE_EVENT_MAP();// event map initialization

As shown in the picture

© 2013 Camshare Inc. Page 33


Camfrog Bot 6.0

Switch to the file ”plugin_bot_manager.cpp” and add the following code:

// 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()

// the function itself where the event is processed


void plugin_bot_manager::on_im_message(pkt_t &pkt)
{
std::string nickname = std::string(pkt[0x01]);// nickname which sent the event
std::string text = std::string(pkt[0x04]); // the text which was sent

// 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());
}

Choose Debug->Build Solution in the menu or just press F7.

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:

© 2013 Camshare Inc. Page 34


Camfrog Bot 6.0

Other events available to the plugin are described in the document "Camfrog Bot SDK.chm".

© 2013 Camshare Inc. Page 35