Professional Documents
Culture Documents
0 for Windows
Developer’s Guide
Camfrog Bot 6.0 for Windows Developer's Guide
Table of Contents
Introduction ................................................................................................................................................... 3
“Low-level” development .............................................................................................................................. 3
Plug-in module SDK ....................................................................................................................................... 3
Plug-In Module Architecture ......................................................................................................................... 4
Functions Description .................................................................................................................................... 5
Callback functions exported by the bot: ................................................................................................... 5
Callback functions exported by the plug-in: .............................................................................................. 8
Structures Description ................................................................................................................................. 12
Events Description ....................................................................................................................................... 15
Chat Room Connection Events ................................................................................................................ 15
Central Server Instant Message Effects ................................................................................................... 15
Chatroom text/talk/users Events ............................................................................................................ 16
Bot to Bot Events ..................................................................................................................................... 18
Service Channel Events ............................................................................................................................ 18
Plug-in to Bot Events ............................................................................................................................... 19
Settings Events ........................................................................................................................................ 21
Window XML Description ............................................................................................................................ 22
Examples .................................................................................................................................................. 28
Introduction
Welcome to the Camfrog Bot Developer's Guide. If you are a new Camfrog Bot user please start by
reading Camfrog Bot User Guide. This manual describes the Camfrog Bot plug-in modules
architecture and the process of custom plug-in modules creation.
Camfrog Bot is a plug-in oriented application which allows users to increase the default
functionality of application by developing and using their own plug-in modules.
There are two basic ways of plug-in modules development, which Camfrog Bot application
performs: “low-level” development and plug-in SDK.
“Low-level” development
This way performs the very basic, but flexible development tools which could be useful for Delphi
or Visual Basic developers or for those who want to implement their own SDK according to their
purposes, because much high-level implementation routine is required.
In addition to the “low-level” tools for modules development, Camfrog Bot provides easy-to-use
object-oriented SDK where most of the routines are already implemented. Here is the list of features
performed by this SDK:
This way of implementation makes the code more clear and compact. It is strongly recommended
for C++ developers to use this SDK.
Camfrog Bot SDK depends on the ‘boost’ libraries which can be downloaded from:
http://www.boost.org/
This article describes plug-in modules architecture for developers to write their own plug-ins. See
also the sources of the sample “Version” plug-in we supply with Camfrog Bot.
All the events that Camfrog Bot 5.0 provides to the modules are divided into several types (see the
Events Description section for more details).
Every plug-in module subscribes on a group (groups) of events and receives events from these
groups only. Every module has its own unique 8-byte id. For example, the Trivia game plug-in has a
CSLLCTRV id. Invent your own id for your plug-in.
The communication between the plug-in modules and the bot is implemented via several callback
functions (see the Functions Description section for more details).
To build the module's settings window we use xml (see the Window XML Description for more
details). There are three types of xml we use:
the first one contains a list of the bot's controls and is loaded once on the first plugin starts
up;
the second one contains the form with the list of controls and their parameters;
the third one contains the current state of the window – it is a communication protocol
between the plugin and the bot used to notify the plugin about settings changes and get an
appropriate response.
Functions Description
cfbot_subscribe
cfbot_unsubscribe
cfbot_pushevent
cfbot_init_settings
cfbot_initialize
cfbot_finalize
cfbot_add_client
cfbot_remove_client
cfbot_plugininformation
cfbot_pushevent
cfbot_subscribe
The cfbot_subscribe function subscribes the plug-in on a group(s) of events.
Syntax
);
Parameters
context [in]
plugin_id [in]
events_type [in]
cfbot_unsubscribe
The cfbot_unsubscribe function unsubscribes the plug-in from a group(s) of events.
Syntax
);
Parameters
context [in]
plugin_id [in]
events_type [in]
cfbot_pushevent
The cfbot_pushevent function is called by the plug-in to make the bot process data.
Syntax
);
Parameters
context [in]
plugin_id [in]
bot_name [in]
bot name
event_data [in]
event_size [in]
cfbot_init_settings
The cfbot_init_settings function is called by the plug-in to initialize the GUI engine for this
module (windows specific).
Syntax
);
Parameters
context [in]
plugin_id [in]
event_data [in]
event_size [in]
cfbot_initialize
The cfbot_initialize function is called by the bot on plug-in loading to initialize it.
Syntax
);
Parameters
callbacks [in]
context [in]
Return value
cfbot_finalize
The cfbot_finalize function is called by the bot on plug-in unloading from memory.
Syntax
);
cfbot_add_client
The cfbot_add_client function is called when the plug-in is turned on to add bots that are going to
use it.
Syntax
);
Parameters
bot_name [in]
work_dir [in]
Return value
cfbot_remove_client
The cfbot_remove_client function is called when the plug-in is turned off or removed.
Syntax
);
Parameters
bot_name [in]
cfbot_plugininformation
The cfbot_plugininformation function is called by the bot on plug-in loading to get plug-in
information (unique ID, version, author, author's e-mail and web-page).
Syntax
);
Parameters
info [in]
cfbot_pushevent
The cfbot_pushevent function is called by the bot to make the plug-in process data.
Syntax
);
Parameters
bot_name [in]
event_data [in]
event_size [in]
Structures Description
CFBOT_PLUGININFORMATION
CFBOT_CALLBACKS
CFBOT_PLUGIN_CALLBACKS
CFBOT_PLUGININFORMATION
Syntax
short pluginversion;
short desired_botversion;
char uniqid[9];
char plugindescription[512];
char authors[512];
char email[512];
char http[512];
} CFBOT_PLUGININFORMATION
Members
pluginversion
plug-in module version
desired_botversion
required bot version
uniqid
unique module ID. 8 chars + '\0'
plugindescription
module information
authors
module’s authors
email
module’s authors’ e-mail address
http
module’s authors’ web page
CFBOT_CALLBACKS
The CFBOT_CALLBACKS structure contains the callback functions exported by the bot.
Syntax
void cfbot_subscribe;
void cfbot_unsubscribe;
void cfbot_pushevent;
void cfbot_init_settings;
} CFBOT_CALLBACKS;
Members
cfbot_subscribe
cfbot_subscribe function
cfbot_unsubscribe
cfbot_unsubscribe function
cfbot_pushevent
cfbot_pushevent function
cfbot_init_settings
cfbot_init_settings function
CFBOT_PLUGIN_CALLBACKS
Syntax
int cfbot_initialize;
void cfbot_finalize;
int cfbot_add_client;
void cfbot_remove_client;
void cfbot_plugininformation;
void cfbot_pushevent;
} CFBOT_PLUGIN_CALLBACKS;
Members
cfbot_initialize
the cfbot_initialize function
cfbot_finalize
the cfbot_finalize function
cfbot_add_client
the cfbot_add_client function
cfbot_remove_client
the cfbot_remove_client function
cfbot_plugininformation
the cfbot_plugininformation function
cfbot_pushevent
the cfbot_pushevent function
Events Description
Settings events
BOT_EVENT_ROOM_CONNECTED An empty packet meaning that the bot is connected to a chat room.
(0x0101) This packet is also delivered if the module is turned off and then
on.
BOT_EVENT_ROOM_DENIED An event that means the bot has been denied entry to a chat room.
(0x0102)
deny reason (0x01) std::string Reason for the denial.
BOT_EVENT_ROOM_KILLED An event that means the bot has been kicked from the chat room.
(0x0103)
kick reason (0x01) std::string Reason for the kick.
BOT_EVENT_ROOM_DISCONNECTED An empty packet meaning that the bot has disconnected from the
(0x0104) chat room.
attributes (0x05) unsigned This value can be set to "0"; in this case the following parameters
char are absent and the text has the default font and size
effects (0x08) unsigned This value can contain the following flags: CFE_BOLD |
long CFE_ITALIC | CFE_UNDERLINE meaning bold, italic and
underlined text respectively.
pitch and family unsigned Message text style and font family.
(0x0A) char
BOT_EVENT_ROOM_IN A packet that is delivered every time the bot connects to a room, a
(0x0401) new user connects to a room or a user's flags change. This packet is
also delivered if the plug-in is turned off and then on. When the bot
enters a room this event repeats for every user in that room.
count (0x04) int In case of the bot logging on to a chat room this field will be set to
a value corresponding to the number of users in that room. In other
cases it will be "1".
topic text (0x02) std::string Topic text. Available only if state is set to "1"
attributes (0x03) unsigned The attributes value can be set to "0". In this case the following
char parameters are absent and the text has the default font and size.
effects (0x06) unsigned This value can contain the following flags: CFE_BOLD |
long CFE_ITALIC | CFE_UNDERLINE meaning bold, italic and
underlined text respectively.
pitch and family (0x08) unsigned Message text style and font family.
char
BOT_EVENT_ROOM_NAME room name (0x01) std::string Current room name (on room connection). This packet will also be
(0x0407) delivered if the module is turned off and then on.
BOT_EVENT_ROOM_TIMER An empty message that is received every 100 msec if the bot is
(0x1001) connected to a chat room
BOT_SIGNAL_EVENT An empty message meaning that a signal has been sent to the bot
(0x2201) (linux specific)
nickname from (0x01) std::string Nickname of the user who has issued the kick.
nickname from (0x01) std::string The user who has changed the option.
option value (0x02) std::string New value for the changed option.
nickname from (0x01) std::string Nickname of the user who has issued the punishment.
reason (0x02) std::string Reason for the punishment. This message consists of two parts, e.g.
"ExpireTime ReasonMessage". The expire time is separated from
the reason message by a space
nickname from (0x01) std::string Nickname of the user who has lifted the punishment.
nickname from (0x01) std::string The user who has issued the ban.
nickname from (0x01) std::string The user who has lifted the ban.
nickname from (0x01) std::string Nickname of the user who has issued the block.
nickname from (0x01) std::string Nickname of the user who has lifted the block.
nickname from (0x01) std::string Nickname of the user who has issued the promotion.
nickname from (0x01) std::string Nickname of the user who has revoked the status in question.
last role (0x02) std::string The status that has been revoked.
PLUGIN_EVENT_DISCONNECT A command from the plug-in to the bot to disconnect from the
(0x0151) active room and central server. An empty packet.
PLUGIN_EVENT_RESUME A command from the plug-in to the bot to connect to the last active
(0x0152) room. An empty packet.
PLUGIN_EVENT_PAUSE A command from the plug-in to the bot to disconnect from the last
(0x0153) active room. An empty packet.
PLUGIN_EVENT_IM A command from the plug-in to the bot to send an instant message.
(0x0251)
nickname to (0x01) std::string Instant message recipient.
attributes (0x03) unsigned The attributes value can be set to "0". In this case the following
char parameters are absent and the text has the default font and size.
effects (0x06) unsigned This value can contain the following flags: CFE_BOLD |
long CFE_ITALIC | CFE_UNDERLINE meaning bold, italic and
underlined text respectively.
pitch and family (0x8) unsigned Message text style and font family.
char
PLUGIN_EVENT_ROOM_TEXT A command from the plug-in to the bot to send a message to the
(0x0451) room.
attributes (0x02) unsigned The attributes value can be set to "0". In this case the following
char parameters are absent and the text has the default font and size.
effects (0x05) unsigned This value can contain the following flags: CFE_BOLD |
long CFE_ITALIC | CFE_UNDERLINE meaning bold, italic and
underlined text respectively.
pitch and family (0x07) unsigned Message text style and font family.
char
Settings Events
BOT_EVENT_SETTINGS_GET An empty packet requesting the current state XML from the plug-
(0x8001) in.
BOT_EVENT_SETTINGS_PROCESS xml (0x01) std::string An XML with the interface state after a user's action.
(0x8002)
BOT_EVENT_SETTINGS_APPLY interface state (0x01) std::string An XML with the interface state after the “Apply” button has been
(0x8003) pressed.
BOT_EVENT_SETTINGS_CANCEL An empty packet meaning that the “Cancel” button has been
(0x8004) pressed.
PLUGIN_SETTINGS_GET_REPLY xml (0x01) std::string The plug-in module's current state xml in reply to a
(0x8051) BOT_EVENT_SETTINGS_GET request.
PLUGIN_SETTINGS_STATE_REPLY xml (0x01) std::string The plug-in module's current state xml with the interface reaction
(0x8052) on user's action (reply to a
BOT_EVENT_SETTINGS_PROCESS request).
Form
Button
Checkbox
Edit
Label
Combo box
List view
Spin edit
Group box
Folder dialog
File dialog
Examples
Form
Button
<Button Id = "ButtonId1"
X = "x" // coordinate X
Y = "y" // coordinate Y
Width = "width"
Height = "height"
IsEnabled = "isEnabled" // clickable or not
> Text // button text
</Button>
Checkbox
<CheckBox Id = "CheckId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
IsChecked = "isChecked" // checked or not
>Text // checkbox text
</CheckBox>
<RadioGroup>
<RadioButton Id = "RadioId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
IsChecked = "isChecked"
>Text
</RadioButton>
<RadioButton Id = "RadioId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
IsChecked = "isChecked"
>Text
</RadioButton>
</RadioGroup>
Edit
<Edit Id = "EditId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
>Text
</Edit>
Label
<Lable Id = "StaticId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
>Text
</Lable>
Combo Box
<ComboBox Id = "ComboBoxId"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
SelectedIndex = "selectedIndex">
List View
<ListView Id = "ListViewId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
SelectedIndex = "selectedIndex">
Spin edit
<SpinEdit Id = "SpingEditId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
isEnabled = "isEnabled"
MinValue = "minValue" // minimal value
MaxValue = "maxValue" // maximal value
Step = "step" // step
>CurrentValue
</SpinEdit>
Group Box
<GroupBox Id = "GroupBoxId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
>Text
</GroupBox>
FormState = {new,update,close}
isEnabled = {true,false}
isChecked = {true,false}
selectedIndex = {-1, 0, 1, 2, 3,...}
index = { 0, 1, 2, 3,...}
x,y – widget coordinates
width, height – widget size
Text – widget text
ItemText – item text
Folder Dialog
File Dialog
<Form Id = 'FileDialog'
Filename = "begin.file">
<Filter Mask = "FilesMask">
<FilenameExtension>Extension</FilenameExtension>
<FilenameExtension>Extension</FilenameExtension>
<FilenameExtension>Extension</FilenameExtension>
</Filter>
<Filter Mask = "OtherMask">
<FilenameExtension>Extension</FilenameExtension>
<FilenameExtension>Extension</FilenameExtension>
<FilenameExtension>Extension</FilenameExtension>
</Filter>
</Form>
Examples
<Form Id = "FolderDialog">
<FolderPath>folderpath</FolderPath>
<DialogState>state</DialogState>
</Form>
<Form Id = "FileDialog">
<FilePath>filepath</FilePath>
<DialogState>state</DialogState>
</Form>
Please note: Widget IDs FolderDialog and FileDialog are reserved and you cannot assign them.