Beruflich Dokumente
Kultur Dokumente
0 for Windows
Developers 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
Page 2
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.
Here is the list of features this way provides:
-
This way of implementation makes the code more clear and compact. It is strongly recommended
for C++ developers to use this SDK.
2013 Camshare Inc.
Page 3
Camfrog Bot SDK depends on the boost libraries which can be downloaded from:
http://www.boost.org/
See ${CFBOT_INSTALL_DIR}\Help\Camfrog Bot SDK.chm for more information.
up;
the first one contains a list of the bot's controls and is loaded once on the first plugin starts
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.
Page 4
Functions Description
Exported by the bot:
cfbot_subscribe
cfbot_unsubscribe
cfbot_pushevent
cfbot_init_settings
cfbot_subscribe
The cfbot_subscribe function subscribes the plug-in on a group(s) of events.
Syntax
void callback cfbot_subscribe(
__in
void *CONTEXT,
__in
char *PLUGIN_ID,
__in
u_long EVENTS_TYPE
);
Parameters
Page 5
context [in]
a pointer to the plug-in interface
plugin_id [in]
unique module ID. 8 chars + '\0'
events_type [in]
The group(s) of events to be subscribed on.
cfbot_unsubscribe
The cfbot_unsubscribe function unsubscribes the plug-in from a group(s) of events.
Syntax
void callback cfbot_unsubscribe(
__in
void *CONTEXT,
__in
char *PLUGIN_ID,
__in
u_long EVENTS_TYPE
);
Parameters
context [in]
a pointer to the plug-in interface
plugin_id [in]
unique module ID. 8 chars + '\0'
events_type [in]
The group(s) of events to be subscribed on.
cfbot_pushevent
The cfbot_pushevent function is called by the plug-in to make the bot process data.
Page 6
Syntax
void callback cfbot_pushevent(
__in
void *CONTEXT,
__in
char *PLUGIN_ID,
__in
char* BOT_NAME,
__in
char *EVENT_DATA,
__in
int EVENT_SIZE
);
Parameters
context [in]
a pointer to the plug-in interface
plugin_id [in]
unique module ID. 8 chars + '\0'
bot_name [in]
bot name
event_data [in]
data to be processed by the bot
event_size [in]
data size (in bytes)
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
Page 7
void *CONTEXT,
__in
char *PLUGIN_ID,
__in
char *EVENT_DATA,
__in
int *EVENT_SIZE
);
Parameters
context [in]
a pointer to the plug-in interface
plugin_id [in]
unique module ID. 8 chars + '\0'
event_data [in]
initial XML data
event_size [in]
data size (in bytes)
CFBOT_CALLBACKS *callbacks,
__in
void *context
);
Page 8
Parameters
callbacks [in]
A pointer to the CFBOT_CALLBACKS structure which contains the list of functions
exported by the bot
context [in]
A pointer to plug-in interface
Return value
Zero if an error has occurred, non-zero if successful.
cfbot_finalize
The cfbot_finalize function is called by the bot on plug-in unloading from memory.
Syntax
void callback cfbot_finalize (
);
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
int callback cfbot_add_client (
__in
char* bot_name,
__in
char* work_dir
);
Parameters
2013 Camshare Inc.
Page 9
bot_name [in]
Name of a bot that will be using the plug-in
work_dir [in]
Path to the bot profile directory
Return value
Zero if an error has occurred, non-zero if successful.
cfbot_remove_client
The cfbot_remove_client function is called when the plug-in is turned off or removed.
Syntax
char* bot_name,
);
Parameters
bot_name [in]
Name of a bot that will no longer be using the plug-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
void callback cfbot_plugininformation (
__in
CFBOT_PLUGININFORMATION *info,
);
Page 10
Parameters
info [in]
A pointer to the CFBOT_PLUGININFORMATION structure which contains the plug-in
information
cfbot_pushevent
The cfbot_pushevent function is called by the bot to make the plug-in process data.
Syntax
void callback cfbot_pushevent (
__in
char* bot_name,
__in
char *event_data,
__in
int event_size
);
Parameters
bot_name [in]
Name of the bot the data belongs to
event_data [in]
Data to be processed by the bot
event_size [in]
data size (in bytes)
Page 11
Structures Description
CFBOT_PLUGININFORMATION
CFBOT_CALLBACKS
CFBOT_PLUGIN_CALLBACKS
CFBOT_PLUGININFORMATION
The CFBOT_PLUGININFORMATION structure contains the plug-in module information.
Syntax
typedef struct CFBOT_PLUGININFORMATION {
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
2013 Camshare Inc.
Page 12
modules authors
email
modules authors e-mail address
http
modules authors web page
CFBOT_CALLBACKS
The CFBOT_CALLBACKS structure contains the callback functions exported by the bot.
Syntax
typedef struct CFBOT_CALLBACKS {
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
The CFBOT_PLUGIN_CALLBACKS structure contains the list of functions exported by the
plug-in.
2013 Camshare Inc.
Page 13
Syntax
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
Page 14
Events Description
Chat room connection events
Central server instant message events
Chat room text/talk/users events
Bot to bot events
Service channel events
Plug-in to bot events
Settings events
Event
Fields
Field type
Description
BOT_EVENT_ROOM_CONNECTED
(0x0101)
This packet is also delivered if the module is turned off and then
on.
BOT_EVENT_ROOM_DENIED
(0x0102)
An event that means the bot has been denied entry to a chat room.
deny reason (0x01)
std::string
BOT_EVENT_ROOM_KILLED
(0x0103)
std::string
BOT_EVENT_ROOM_DISCONNECTED
An empty packet meaning that the bot has disconnected from the
(0x0104)
chat room.
Fields
Field type
BOT_EVENT_IM
Description
The bot has received an instant message.
(0x0201)
nickname from (0x01) std::string
feedback (0x02)
int
age (0x03)
unsigned
char
Page 15
text (0x04)
std::string
Message text.
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
unsigned
size (0x06)
char
color (0x07)
unsigned
long
effects (0x08)
unsigned
long
charset (0x09)
unsigned
char
pitch
and
family unsigned
(0x0A)
char
std::string
Event
Fields
Field type
Description
BOT_EVENT_ROOM_IN
(0x0401)
std::string
User's nickname.
flags (0x02)
unsigned
Flags description:
long
audio
video
female user
OP or OPPLUS
FRIEND
16
OWNER
32
punished user
64
BOT
128
privacy mode
256
ignored user
512
audio blocked
1024
PRO user
2048
age (0x03)
unsigned
User's age.
char
Page 16
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".
BOT_EVENT_ROOM_TALK
(0x0403)
unsigned
char
nickname (0x02)
std::string
BOT_EVENT_ROOM_MOTD
(0x0404)
std::string
BOT_EVENT_ROOM_TOPIC
(0x0405)
state (0x01)
unsigned
char
topic text (0x02)
std::string
BOT_EVENT_ROOM_TEXT
(0x0406)
nickname (0x01)
std::string
text (0x02)
std::string
Message text.
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.
unsigned
size (0x04)
char
color (0x05)
unsigned
long
effects (0x06)
unsigned
long
charset (0x07)
unsigned
char
pitch and family (0x08) unsigned
char
BOT_EVENT_ROOM_NAME
(0x0407)
std::string
std::string
Current room name (on room connection). This packet will also be
delivered if the module is turned off and then on.
Page 17
Event
Fields
Field type
BOT_EVENT_BOT_2_BOT
(0x0801)
Description
A plug-in to plug-in message.
UNIQID (0x01)
SENDER
std::string
UNIQID std::string
(0xFFFF)
BOT_EVENT_MODULES
(0x0802)
int
UNIQID (0x02 + I)
std::string
BOT_EVENT_ROOM_TIMER
(0x1001)
BOT_SIGNAL_EVENT
An empty message meaning that a signal has been sent to the bot
(0x2201)
(linux specific)
Event
Fields
Field type
BOT_EVENT_ROOM_KICK
(0x4001)
std::string
reason (0x02)
std::string
std::string
std::string
BOT_EVENT_ROOM_PUNISH
(0x4003)
BOT_EVENT_ROOM_SETOPT
(0x4002)
Description
std::string
reason (0x02)
Reason for the punishment. This message consists of two parts, e.g.
std::string
time_t
A user has been unpunished.
Page 18
(0x4004)
nickname to (0x00)
std::string
std::string
Ban list entry for the user in question. Ban list entry format:
deny|allow nick|ip|nick_ip [nickname] [ip mask] no-expire|expire
interval
std::string
Ban list entry for the user in question. Ban list entry format:
deny|allow nick|ip|nick_ip [nickname] [ip mask] no-expire|expire
interval
std::string
std::string
nickname to (0x00)
std::string
std::string
BOT_EVENT_ROOM_DEOP
(0x4010)
(0x4009)
std::string
std::string
Event
Fields
Field type
Description
PLUGIN_EVENT_DISCONNECT
(0x0151)
PLUGIN_EVENT_RESUME
A command from the plug-in to the bot to connect to the last active
(0x0152)
Page 19
PLUGIN_EVENT_PAUSE
A command from the plug-in to the bot to disconnect from the last
(0x0153)
PLUGIN_EVENT_IM
(0x0251)
nickname to (0x01)
std::string
text (0x02)
std::string
Message text.
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.
unsigned
size (0x04)
char
color (0x05)
unsigned
long
effects (0x06)
unsigned
long
charset (0x07)
unsigned
char
pitch and family (0x8) unsigned
char
font name (0x09)
std::string
PLUGIN_EVENT_ROOM_TEXT
(0x0451)
room.
text (0x01)
std::string
Message text.
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.
unsigned
size (0x03)
char
color (0x04)
unsigned
long
effects (0x05)
unsigned
long
charset (0x06)
unsigned
char
pitch and family (0x07) unsigned
char
font name (0x08)
PLUGIN_BOT_2_BOT
std::string
Page 20
(0x0851)
another plug-in.
UNIQID (0x01)
std::string
Recipient plug-in.
Settings Events
Event
Fields
Field type
Description
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
std::string
An XML with the interface state after the Apply button has been
(0x8002)
BOT_EVENT_SETTINGS_APPLY
(0x8003)
pressed.
BOT_EVENT_SETTINGS_CANCEL
(0x8004)
pressed.
PLUGIN_SETTINGS_GET_REPLY
xml (0x01)
std::string
(0x8051)
PLUGIN_SETTINGS_STATE_REPLY
(0x8052)
xml (0x01)
std::string
The plug-in module's current state xml with the interface reaction
on
user's
action
(reply
to
BOT_EVENT_SETTINGS_PROCESS request).
Page 21
Form
Button
Checkbox
Radio group and radio buttons
Edit
Label
Combo box
List view
Spin edit
Group box
Folder dialog
File dialog
Examples
Form
<Form
Id = "FormId"
Width = "width"
Height = "height"
Title = "title"
Default=Some Widget>
</Form>
// unique id
Page 22
Button
<Button
Id = "ButtonId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
> Text
// coordinate X
// coordinate Y
// clickable or not
// button text
</Button>
Checkbox
<CheckBox
Id = "CheckId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
IsChecked = "isChecked"
>Text
// checked or not
// checkbox text
</CheckBox>
Page 23
<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>
Page 24
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">
<ComboBoxItem Index = "index1"
>ItemText1
</ComboBoxItem>
<ComboBoxItem Index = "index2"
>ItemText2
</ComboBoxItem>
</ComboBox>
Page 25
List View
<ListView Id = "ListViewId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
IsEnabled = "isEnabled"
SelectedIndex = "selectedIndex">
<ListViewItem Index = "index1"
>ItemText1
</ListViewItem>
<ListViewItem Index = "index2"
>ItemText2
</ListViewItem>
</ListView>
Spin edit
<SpinEdit
Id = "SpingEditId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
isEnabled = "isEnabled"
MinValue = "minValue"
MaxValue = "maxValue"
Step = "step"
>CurrentValue
// minimal value
// maximal value
// step
</SpinEdit>
Group Box
<GroupBox
Id = "GroupBoxId1"
X = "x"
Y = "y"
Width = "width"
Height = "height"
>Text
</GroupBox>
Page 26
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
<Form
Id = 'FolderDialog'
RootFolder = "rootfolder"
>
</From>
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>
Page 27
Examples
<Form Id = "FolderDialog">
<FolderPath>folderpath</FolderPath>
<DialogState>state</DialogState>
</Form>
<Form Id = "FileDialog">
<FilePath>filepath</FilePath>
<DialogState>state</DialogState>
</Form>
Page 28
Please note: Widget IDs FolderDialog and FileDialog are reserved and you cannot assign them.
Page 29