Camfrog Bot Developer's Guide

Camfrog Bot 6.0 for Windows Developer’s Guide

Camfrog Bot 6.0 for Windows Developer's Guide

© 2013 Camshare Inc. Page 2

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.

Here is the list of features this way provides:

- Camfrog Bot application callbacks;

- Plug-in module callbacks;

- Headers of the packets for application-module (and vice versa) communication;

- XML description of UI elements (buttons, lists, group boxes etc).

This manual describes “low-level” way of implementation.

Plug-in module SDK

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:

- Configuration file parser;

- Camfrog Bot packets handlers which could be overridden by the developer;

- UI engine which provides methods for constructing interface elements (no need to parse

XML).

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/

See ‘${CFBOT_INSTALL_DIR}\Help\Camfrog Bot SDK.chm’ for more information.

Plug-In Module Architecture

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.

http://www.boost.org/



Functions Description

Exported by the bot:

cfbot_subscribe

cfbot_unsubscribe

cfbot_pushevent

cfbot_init_settings

Exported by the plug-in:

cfbot_initialize

cfbot_finalize

cfbot_add_client

cfbot_remove_client

cfbot_plugininformation

cfbot_pushevent

Callback functions exported by the bot:

cfbot_subscribe

The cfbot_subscribe function subscribes the plug-in on a group(s) of events.

Syntax

Parameters

void callback cfbot_subscribe(

__in void *CONTEXT,

__in char *PLUGIN_ID,

__in u_long EVENTS_TYPE

);



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

Parameters

context [in]


plugin_id [in]


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.

void callback cfbot_unsubscribe(

__in void *CONTEXT,


__in u_long EVENTS_TYPE

);



Syntax

Parameters

context [in]


plugin_id [in]


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

void callback cfbot_pushevent(

__in void *CONTEXT,


__in char* BOT_NAME,

__in char *EVENT_DATA,

__in int EVENT_SIZE

);



Parameters

context [in]


plugin_id [in]


event_data [in]

initial XML data

event_size [in]


Callback functions exported by the plug-in:

cfbot_initialize

The cfbot_initialize function is called by the bot on plug-in loading to initialize it.

Syntax

int callback cfbot_initialize(

__in CFBOT_CALLBACKS *callbacks,

__in void *context

);

void callback cfbot_init_settings(

__in void *CONTEXT,


__in char *EVENT_DATA,

__in int *EVENT_SIZE

);



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

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

int callback cfbot_add_client (

__in char* bot_name,

__in char* work_dir

);

void callback cfbot_finalize (

);



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

Parameters

bot_name [in]

Name of a bot that will no longer be using the plug-in


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,

);

void callback cfbot_remove_client (


);



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

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]


void callback cfbot_pushevent (


__in char *event_data,

__in int event_size

);



Structures Description

CFBOT_PLUGININFORMATION

CFBOT_CALLBACKS

CFBOT_PLUGIN_CALLBACKS

CFBOT_PLUGININFORMATION

The CFBOT_PLUGININFORMATION structure contains the plug-in module information.

Syntax

Members

pluginversion

plug-in module version

desired_botversion

required bot version

uniqid


plugindescription

module information

authors

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



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

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.

typedef struct CFBOT_CALLBACKS {

void cfbot_subscribe;

void cfbot_unsubscribe;

void cfbot_pushevent;

void cfbot_init_settings;

} CFBOT_CALLBACKS;



Syntax

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


the cfbot_plugininformation function

cfbot_pushevent

the cfbot_pushevent function

typedef struct CFBOT_PLUGIN_CALLBACKS {

int cfbot_initialize;

void cfbot_finalize;

int cfbot_add_client;

void cfbot_remove_client;

void cfbot_plugininformation;

void cfbot_pushevent;

} CFBOT_PLUGIN_CALLBACKS;



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

Chat Room Connection Events

Event Fields Field type Description

BOT_EVENT_ROOM_CONNECTED

(0x0101)

An empty packet meaning that the bot is connected to a chat room.

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 Reason for the denial.

BOT_EVENT_ROOM_KILLED

(0x0103)

An event that means the bot has been kicked from the chat room.

kick reason (0x01) std::string Reason for the kick.

BOT_EVENT_ROOM_DISCONNECTED

(0x0104)

An empty packet meaning that the bot has disconnected from the

chat room.

Central Server Instant Message Effects


BOT_EVENT_IM

(0x0201)

The bot has received an instant message.

nickname from (0x01) std::string Nickname of the message sender.

feedback (0x02) int User's feedback value.

age (0x03) unsigned

char

Age of the message sender.



text (0x04) std::string Message text.

attributes (0x05) unsigned

char

This value can be set to "0"; in this case the following parameters

are absent and the text has the default font and size

size (0x06) unsigned

char

Message text size.

color (0x07) unsigned

long

Message text color.

effects (0x08) unsigned

long

This value can contain the following flags: CFE_BOLD |

CFE_ITALIC | CFE_UNDERLINE meaning bold, italic and

underlined text respectively.

charset (0x09) unsigned

char

Message text charset.

pitch and family

(0x0A)

unsigned

char

Message text style and font family.

font name (0x0B) std::string Message text font.

Chatroom text/talk/users Events


BOT_EVENT_ROOM_IN

(0x0401)

A packet that is delivered every time the bot connects to a room, a

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.

nickname (0x01) std::string User's nickname.

flags (0x02) unsigned

long

Flags description:

audio 1

video 2

female user 4

OP or OPPLUS 8

FRIEND 16

OWNER 32

punished user 64

BOT 128

privacy mode 256

ignored user 512

audio blocked 1024

PRO user 2048

age (0x03) unsigned

char

User's age.



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)

A room talk event.

state (0x01) unsigned

char

A state value of 1 means start talk, 0 - stop talk

nickname (0x02) std::string Nickname is available only if state is set to "1"

BOT_EVENT_ROOM_MOTD

(0x0404)

The room's Message of the day.

MOTD text (0x01) std::string Message of the day text.

BOT_EVENT_ROOM_TOPIC

(0x0405)

The room topic.

state (0x01) unsigned

char

A state value of 1 means topic on, 0 - topic off

topic text (0x02) std::string Topic text. Available only if state is set to "1"

BOT_EVENT_ROOM_TEXT

(0x0406)

Room text.

nickname (0x01) std::string Nickname of the massage's author. An empty nickname field means

a server message.



char

The attributes value can be set to "0". In this case the following

parameters are absent and the text has the default font and size.


char

Message text size.


long

Message text color.


long





char


pitch and family (0x08) unsigned

char


font name (0x09) std::string Message text font.

BOT_EVENT_ROOM_NAME

(0x0407)

room name (0x01) std::string Current room name (on room connection). This packet will also be

delivered if the module is turned off and then on.



Bot to Bot Events


BOT_EVENT_BOT_2_BOT

(0x0801)

A plug-in to plug-in message.

UNIQID (0x01) std::string Unique ID of the recipient plug-in.

SENDER UNIQID

(0xFFFF)

std::string Unique ID of the sender plug-in.

BOT_EVENT_MODULES

(0x0802)

A plug-in can request the list of other modules.

COUNT (0x01) int The number of installed modules.

UNIQID (0x02 + I) std::string Installed modules' unique IDs. I = count.

BOT_EVENT_ROOM_TIMER

(0x1001)

An empty message that is received every 100 msec if the bot is

connected to a chat room

BOT_SIGNAL_EVENT

(0x2201)

An empty message meaning that a signal has been sent to the bot

(linux specific)

Service Channel Events


BOT_EVENT_ROOM_KICK

(0x4001)

A user has been kicked from the chat room.

nickname to (0x00) std::string Nickname of the kicked user.

nickname from (0x01) std::string Nickname of the user who has issued the kick.

reason (0x02) std::string Kick reason (if stated).

BOT_EVENT_ROOM_SETOPT

(0x4002)

Room options have been set.

option (0x00) std::string The option that has been changed.

nickname from (0x01) std::string The user who has changed the option.

option value (0x02) std::string New value for the changed option.

BOT_EVENT_ROOM_PUNISH

(0x4003)

A user has been punished.

nickname to (0x00) std::string Nickname of the punished user.

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

expire time time_t

BOT_EVENT_ROOM_UNPUNISH A user has been unpunished.



(0x4004) nickname to (0x00) std::string Nickname of the unpunished user.

nickname from (0x01) std::string Nickname of the user who has lifted the punishment.

BOT_EVENT_ROOM_BAN_ADD

(0x4005)

A user has been banned.

ban list record (0x00) 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

nickname from (0x01) std::string The user who has issued the ban.

BOT_EVENT_ROOM_BAN_REMOVE

(0x4006)

A user has been unbanned.

ban list record (0x00) 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

nickname from (0x01) std::string The user who has lifted the ban.

BOT_EVENT_ROOM_BLOCKMIC

(0x4007)

A user's microphone has been blocked.

nickname to (0x00) std::string Nickname of the user in question.

nickname from (0x01) std::string Nickname of the user who has issued the block.

BOT_EVENT_ROOM_UNBLOCKMIC

(0x4008)

A user's microphone has been unblocked.

nickname to (0x00) std::string Nickname of the user in question.

nickname from (0x01) std::string Nickname of the user who has lifted the block.

BOT_EVENT_ROOM_MAKEOP

(0x4009)

A user has got a new role (operator, owner, friend).

nickname to (0x00) std::string Nickname of the promoted user.

nickname from (0x01) std::string Nickname of the user who has issued the promotion.

new role (0x02) std::string User's new role.

BOT_EVENT_ROOM_DEOP

(0x4010)

A user's operator (owner, friend) status has been revoked.

nickname to (0x00) std::string Nickname of the demoted user.

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.

Plug-in to Bot Events


PLUGIN_EVENT_DISCONNECT

(0x0151)

A command from the plug-in to the bot to disconnect from the

active room and central server. An empty packet.

PLUGIN_EVENT_RESUME

(0x0152)

A command from the plug-in to the bot to connect to the last active

room. An empty packet.



PLUGIN_EVENT_PAUSE

(0x0153)

A command from the plug-in to the bot to disconnect from the last

active room. An empty packet.

PLUGIN_EVENT_IM

(0x0251)

A command from the plug-in to the bot to send an instant message.

nickname to (0x01) std::string Instant message recipient.



char




char

Message text size.


long

Message text color.


long





char



char



PLUGIN_EVENT_ROOM_TEXT

(0x0451)

A command from the plug-in to the bot to send a message to the

room.



char




char

Message text size.


long

Message text color.


long





char



char



PLUGIN_BOT_2_BOT A command from the plug-in to the bot to send a message to



(0x0851) another plug-in.

UNIQID (0x01) std::string Recipient plug-in.

Settings Events


BOT_EVENT_SETTINGS_GET

(0x8001)

An empty packet requesting the current state XML from the plug-

in.

BOT_EVENT_SETTINGS_PROCESS

(0x8002)

xml (0x01) std::string An XML with the interface state after a user's action.

BOT_EVENT_SETTINGS_APPLY

(0x8003)

interface state (0x01) std::string An XML with the interface state after the “Apply” button has been

pressed.

BOT_EVENT_SETTINGS_CANCEL

(0x8004)

An empty packet meaning that the “Cancel” button has been

pressed.

PLUGIN_SETTINGS_GET_REPLY

(0x8051)

xml (0x01) std::string The plug-in module's current state xml in reply to a

BOT_EVENT_SETTINGS_GET request.

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 a

BOT_EVENT_SETTINGS_PROCESS request).



Window XML Description

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" // unique id

Width = "width"

Height = "height"

Title = "title"

Default=”Some Widget”> // widget with default focus

</Form>



Button

Checkbox

<CheckBox Id = "CheckId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"

IsEnabled = "isEnabled"

IsChecked = "isChecked" // checked or not

>Text // checkbox text

</CheckBox>

<Button Id = "ButtonId1"

X = "x" // coordinate X

Y = "y" // coordinate Y

Width = "width"

Height = "height"

IsEnabled = "isEnabled" // clickable or not

> Text // button text

</Button>



Radio group and radio buttons

Edit

<Edit Id = "EditId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"


>Text

</Edit>

<RadioGroup>

<RadioButton Id = "RadioId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"


IsChecked = "isChecked"

>Text

</RadioButton>

<RadioButton Id = "RadioId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"


IsChecked = "isChecked"

>Text

</RadioButton>

</RadioGroup>



Label

Combo Box

<ComboBox Id = "ComboBoxId"

X = "x"

Y = "y"

Width = "width"

Height = "height"


SelectedIndex = "selectedIndex">

<ComboBoxItem Index = "index1"

>ItemText1

</ComboBoxItem>

<ComboBoxItem Index = "index2"

>ItemText2

</ComboBoxItem>

</ComboBox>

<Lable Id = "StaticId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"

>Text

</Lable>



List View

Spin edit

Group Box

<GroupBox Id = "GroupBoxId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"

>Text

</GroupBox>

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

<ListView Id = "ListViewId1"

X = "x"

Y = "y"

Width = "width"

Height = "height"


SelectedIndex = "selectedIndex">

<ListViewItem Index = "index1"

>ItemText1

</ListViewItem>

<ListViewItem Index = "index2"

>ItemText2

</ListViewItem>

</ListView>



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

begin.file - default file

FileMask - discription that will be before list of filename extension

Extension - filename extension of files in this FileMask

<Form Id = 'FileDialog'

Filename = "begin.file">

<Filter Mask = "FilesMask">

<FilenameExtension>Extension</FilenameExtension>



</Filter>

<Filter Mask = "OtherMask">




</Filter>

</Form>

<Form Id = 'FolderDialog' // reserved Id for folder dialog

RootFolder = "rootfolder" // default folder

>

</From>



Examples

Window current state xml template

Folder and file dialog state xml template

folderpath - path of selected folder

state - {true/false} - Ok or Cancel user click

filepath - path of selected file

state - {true/false} - Ok or Cancel user click

<Form Id = "FileDialog">

<FilePath>filepath</FilePath>

<DialogState>state</DialogState>

</Form>

<Form Id = "FolderDialog">

<FolderPath>folderpath</FolderPath>

<DialogState>state</DialogState>

</Form>

<Form Id="Form1">

<CheckBox Id="Checkid">true</CheckBox>

<ComboBox Id="ComboBox1">0</ComboBox>

<Edit Id="Edit1">InnerText</Edit>

<Button>true</Button>

<ListView Id="ListView1" SelectedIndex="1">

<ListViewItem Index="0">Item1</ListViewItem>

<ListViewItem Index="1">Item2</ListViewItem>

</ListView>

<RadioButton Id="Radioid1">true</RadioButton>

<RadioButton Id="Radioid2">false</RadioButton>

<RadioButton Id="Radioid3">false</RadioButton>

<SpinEdit Id = "SpinEditId1">Value</SpinEdit>

</Form>



Please note: Widget IDs FolderDialog and FileDialog are reserved and you cannot assign them.

Date post:	11-Dec-2015
Category:	Documents
Upload:	anonymous-af99dx79vc
View:	440 times
Download:	32 times

Camfrog Bot Developer's Guide

Documents