ChatBlade API Help

CBSampleImplementation::CBSampleImplementation()

Comments:

Constructor.

Sets a few initial sample values.

Parameters:

None

Returns:

None

int

CBSampleImplementation::LoadSlashCommands()

Comments:

This Sample code loads up the Slash Command interface via reading in a file entitled SlashCommands.XML.

It shows how each OnCommandXXX() function can have multiple Slash Commands that map to it.

By providing the Slash Command interface in a user editable XML file, this sample shows one way that Players may be able to configure their own Slash Commands, and no longer be reliant upon Developer dictates.

One of ChatBlades innovative features is the ability to allow Players to alter the Slash Commands to whatever they are accustomed to. This sample allows that to be done via an XML file.

Hopefully Game Developers retain the ability for Players to configure and alter the Slash Command interface, either via an XML file, or in-game via dialogs.

This Sample code reuses a CBCommandMap instance, once for each OnCommandXXX() function.

It then fills that CBCommandMap instance with the Slash Commands which invoke OnCommandXXX() function.

Finally it places the CBCommandMap instance into CBData::vCommandMapArray via CBData::AddCommandMap() so that ChatBlade may use it.

The OnCommandXXX() functions are all static members of the CBSlashCommands class.

The important lines in this sample are:

cbReusableCommandMap.SetPointer(CBData::mCommandFunctionPointerMap[sFunctionName]);

cbReusableCommandMap.SetDescription(sDescription);

cbReusableCommandMap.AddAlias(sAlias);

CBData::AddCommandMap (cbReusableCommandMap);

Called as a result of CBChatHandler::InitializeChat()

Parameters:

None

Returns:

CB_ERROR_CANNOT_OPEN_FILE if SlashCommands.XML cannot be opened.

CB_SUCCESS if the Slash Commands have been loaded into ChatBlade.

int

CBSampleImplementation::LoadChatFilter()

Comments:

Sample function that loads up bad words into CBData::pChatHandler->m_ChatFilter.

This sample reads in the offensive words from Filter.XML and places the words found there into CBData::pChatHandler->m_ChatFilter.

ChatBlade uses the CBChatFilter instance contained in CBChatHandler to enable Chat Filtering.

Game Developers should load this instance with complete words which should be filtered out when a Player turns on the Chat Filter.

Only single words should be loaded into the Chat Filter. Spaces should not be used.

ChatBlade filters out entire words and not portions of words. Therefore all variations of a bad word should be loaded into the Chat Filter.

ChatBlade endeavors to ignore any punctuation found in any offensive text.

Filtered words are replaced with @#!$^ type text.

The important line in this sample is:

CBData::pChatHandler->m_ChatFilter.AddString(sText);

Called as a result of CBChatHandler::InitializeChat().

Parameters:

None

Returns:

CB_ERROR_CANNOT_OPEN_FILE if the function cannot open Filter.XML

CB_SUCCESS

int

CBSampleImplementation::LoadLanguageTables()

Comments:

This sample shows the loading of the Elvish Language Table.

It reads in the words stored in Elvish.XML to fill in the table then adds the Language Table to ChatBlade via CBLanguageTable::AddLanguageTable().

Game Developers should use this example to understand how one might implement loading in various in-game Fantasy/Sci-Fi Languages into a Game.

This example makes use of an XML file, but reading the Language information from a database or another source would work as well.

ChatBlade stores a Map of all the CBLanguageTable instances in CBData::pChatHandler->m_LanguageTableMap.

Each in-game artificial Language should have one instance stored in this Map. The Map is keyed via the LanguageID of the Language. Each Language should have a unique ID.

Each Language Table should be loaded with a variety of short, medium, and long length words that sound like they would be from the target Language.

ChatBlade shall use the words loaded into the Language Table in order to replace real words, when a Character does not fully understand a Chat Message spoken in an in-game Language.

ChatBlade shall endeavor to replace real words with artificial words of similar length.

ChatBlade shall endeavor to make sure that each real word always matches up to the same artificial word in the Language Table.

The case of the artificial word loaded into the Language Table shall be the case that it is displayed in. It is recommended that each word loaded start with an initial Capital letter.

Language Tables are designed for western character sets.

The important lines in this Sample are:

cbElvishLanguageTable.AddWord(sText);

CBLanguageTable::AddLanguageTable(cbElvishLanguageTable);

Called as a result of CBChatHandler::InitializeChat().

Parameters:

None

Returns:

CB_ERROR_CANNOT_OPEN_FILE if this function cannot open Elvish.XML

CB_SUCCESS

int

CBSampleImplementation::LoadAliasList()

Comments:

Sample function that loads up Aliases into CBData::pChatHandler->m_AliasList.

This Sample loads a couple hard-coded Aliases into the Alias List. Real code should load these Alias commands from a Game Database or elsewhere to enable persistence.

ChatBlade uses the CBAliasList instance contained in CBChatHandler to store Player created Alias Commands.

Game Developers should load existing Alias commands into CBData::pChatHandler->m_AliasList.

If an Alias command is typed in by the Player, ChatBlade shall expand that Alias into its game defined actual Slash Command and parameters, as specified when the Alias was created.

The important line from this sample is:

CBData::pChatHandler->m_AliasList.AddAlias(ALIAS_NAME_A, ALIAS_COMMAND_A);

Called as a result of CBChatHandler::InitializeChat().

Parameters:

None

Returns:

CB_ERROR_EMPTY_STRING if an Alias is too short.

CB_ERROR_BAD_CHAT_COMMAND if an Alias does not start with a '/'.

CB_SUCCESS

int

CBSampleImplementation::LoadNicknameList()

Comments:

Sample function that loads up Player created Nicknames into CBData::pChatHandler->m_NicknameList.

This Sample loads a couple hard-coded Nicknames into the Nickname List. Real code should load these Nicknames from a Game Database or elsewhere to enable persistence.

ChatBlade uses the CBNicknameList instance contained in CBChatHandler to handle Nickname expansions for use in /tells.

Game Developers should load existing Nicknames into CBData::pChatHandler->m_NicknameList.

Nicknames are generally short Player created names for other Players Characters to facilitate use in /tells.

Nicknames are created for other Players Characters, not a Players own Characters. Each Nickname list is specific to the User, and is not shared globally.

The important line from this sample is:

CBData::pChatHandler->m_NicknameList.AddNickname(NICKNAME_NICK_A, NICKNAME_CHARACTER_A);

Called as a result of CBChatHandler::InitializeChat().

Parameters:

None

Returns:

CB_ERROR_EMPTY_STRING if a Nickname is too short.

CB_ERROR_DOES_NOT_EXIST if a parameter was left off and a non-existent Nickname was to be removed.

CB_SUCCESS

int

CBSampleImplementation::LoadIgnoreList()

Comments:

Sample function that loads up Character names to Ignore into CBData::pChatHandler->m_IgnoreList.

This Sample loads a couple hard-coded Character Names into the Ignore List. Real code should load these names from a Game Database or elsewhere to enable persistence.

ChatBlade uses the CBIgnoreList instance contained in CBChatHandler to handle Ignore processing of Chat Messages.

Game Developers should load Ignored Character names into CBData::pChatHandler->m_IgnoreList.

Chat Messages with a Source that is a Character name contained in the Ignore List are discarded by ChatBlade and are not available for display.

The string "CBNONE" should not be loaded into the Ignore List. "CBNONE" is the Source for Chat Messages with no Source.

The important line from this sample is:

CBData::pChatHandler->m_IgnoreList.AddCharacter(IGNORE_NAME_A);

Called as a result of CBChatHandler::InitializeChat().

Parameters:

None

Returns:

CB_ERROR_CANNOT_IGNORE if "CBNONE" was attempted to be Ignored.

CB_SUCCESS

int

CBSampleImplementation::LoadSpamFilter()

Comments:

Sample function which loads up the Spam Filter with strings which should be considered Spam.

Any Chat Messages containing strings found in the Spam Filter are discarded and not displayed.

ChatBlade uses the CBSpamFilter instance that is a member of CBChatHandler.

Each Spam string should be loaded via CBData::pChatHandler->m_SpamFilter.AddString().

The ChatBlade Spam Filter blocks Chat Messages containing strings found in the Spam Filter. Even if the string is a sub-string of a longer word, it is considered to be Spam. Case is not important.

Strings containing spaces (phrases) may be loaded into the Spam Filter.

Note: ChatBlade allows Players to dynamically add to, or remove words from the Spam Filter during game play by using the /blockword and /unblockword Slash Commands (by default).

This function is invoked by CBChatHandler::InitializeChat() via CBChatHandler::InitializeSpamFilter().

Parameters:

None

Returns:

CB_SUCCESS

int

CBSampleImplementation::InitializeChatNetworking()

Comments:

Sample function which starts up the Sample Chat Networking.

Used to initialize our Sample Chat Network.

Parameters:

None

Returns:

CB_SUCCESS

int

CBSampleImplementation::DeInitializeChatNetworking()

Comments:

Sample function which should shut down the Sample Chat Networking.

Used to de-initialize our Sample Chat Network and close Winsock.

Parameters:

None

Returns:

CB_SUCCESS

int

CBSampleImplementation::ExpandMacros(

CBSTRING & sLine /*IN OUT*/)

Comments:

This Sample function demonstrates the in-place expansion of a %Macro found in a line of Player typed Chat.

It should replace %T with an imaginary Target Name, and %L with sample text of a Players Coordinates.

Parameters:

sLine

A reference to a line of Player generated Chat which may contain some % macros such as %T or %L. Upon function return this line should have its %Macros replaced with their expanded text information.

Returns:

CB_SUCCESS

int

CBSampleImplementation::OnMessageAddedToTextWindow(

int nGUITextWindowID)

Comments:

Function that gets called by ChatBlade each time a Chat Message is added (or removed) to an CBTextWindowData instance

This function should in turn call into the Developers GUI text window to inform it that its underlying content has changed.

This Sample calls OnTextAddedToGUIWindow() which is a function in the Chat Sample Test Application code (CBMFCTestCLient), which in turns updates the Test Applications text windows.

Developers should notify their GUI text windows whenever this function is invoked. This function is invoked whenever a Chat Message is added or removed from a CBTextWindowData instance that is helping a GUI Text Window/Tab.

Called by CBClientImplementation::OnMessageAddedToTextWindow() when a Chat Message is added to ChatBlade.

Parameters:

nGUITextWindowID

The ID of the GUI Text Window which has had a Chat Message added or removed.

Returns:

CB_SUCCESS

CBSTRING

CBSampleImplementation::GetCharacterName()

Comments:

Sample function that returns the Players current Character name.

ChatBlade shall use this name as the Source for Chat Messages that the Player sends.

Parameters:

None

Returns:

This function should return the current Characters Name.

int

CBSampleImplementation::GetCharacterFaction()

Comments:

Sample function which returns the current Characters FactionID.

For Games which make use of Factions (generally those with PvP elements).

ChatBlade shall use the value returned by this function to supply the FactionID value for Chat Messages generated by the Player.

Parameters:

None

Returns:

This function should return the current Characters FactionID.

CBSTRING

CBSampleImplementation::GetFactionName(

int nFactionID)

Comments:

Sample function which should return a string representation of the supplied FactionID.

ChatBlade uses this string for Chat Messages on the CB_CHANNEL_FACTION channel.

Game Developers should return the Text Name of the supplied FactionID.

Parameters:

nFactionID

The FactionID of an in-game Faction we want the name of.

Returns:

A string representing the name of the supplied FactionID.

CBSTRING

CBSampleImplementation::GetCharacterClassName()

Comments:

Sample function which should return the name of the current Characters Class.

ChatBlade uses this information to support the CB_CHANNEL_CLASS Chat Channel.

Game Developers should return the current Characters Class Name, such as "Bard".

Parameters:

None

Returns:

The name of the current Characters Class.

CBSTRING

CBSampleImplementation::GetCharacterRaceName()

Comments:

Sample function which should return the name of the current Characters Race.

ChatBlade uses this information to support the CB_CHANNEL_RACE Chat Channel.

Game Developers should return the current Characters Race Name, such as "Elf".

Parameters:

None

Returns:

The name of the current Characters Class.

CBSTRING

CBSampleImplementation::GetCharacterLevelAsString()

Comments:

Sample function which should return the string representation of the current Characters Level.

ChatBlade uses this information to support the CB_CHANNEL_LEVEL Chat Channel.

Game Developers should return the current Characters Class Level, such as "12".

Parameters:

None

Returns:

A string representing the current Characters level.

CBSTRING

CBSampleImplementation::GetTargetName()

Comments:

Sample function which should return the string representation of the current Characters Target name.

ChatBlade uses this information to support the /targettell Slash Command

Game Developers should return the current Characters Target name, such as "Palladia", or "Heal Potion".

If the Player does not have a Target this command should return CB_NONE.

Parameters:

None

Returns:

The string name of the Characters Current Target.

CBSTRING

CBSampleImplementation::GetGroupIDCode()

Comments:

Sample function which should return the ID of the current Characters Group.

ChatBlade uses this information to support Group Chat. The GroupID shall be the Destination of the Chat Message.

Game Developers should return the current Characters GroupID as known by the Game.

This value should be a string.

Return CB_NONE if the Character has no Group.

Parameters:

None

Returns:

The GroupID string of the current Characters Group.

CBSTRING

CBSampleImplementation::GetGuildIDCode()

Comments:

Sample function which should return the ID of the current Characters Guild.

ChatBlade uses this information to support Guild Chat. The GuildID shall be the Destination of the Chat Message.

Game Developers should return the current Characters GuildID as known by the Game.

This value should be a string.

Return CB_NONE if the Character has no Guild.

Parameters:

None

Returns:

The GuildID string of the current Characters Guild.

CBSTRING

CBSampleImplementation::GetRaidIDCode()

Comments:

Sample function which should return the ID of the current Characters Raid (Group of Groups).

ChatBlade uses this information to support Raid Chat. The RaidID shall be the Destination of the Chat Message.

Game Developers should return the current Characters RaidID as known by the Game.

This value should be a string.

Return CB_NONE if the Character has no Raid.

Parameters:

None

Returns:

The RaidID string of the current Characters Raid.

CBSTRING

CBSampleImplementation::GetAllianceIDCode()

Comments:

Sample function which should return the ID of the current Characters Alliance (Group of Guilds).

ChatBlade uses this information to support Alliance Chat. The AllianceID shall be the Destination of the Chat Message.

Game Developers should return the current Characters AllianceID as known by the Game.

This value should be a string.

Return CB_NONE if the Character has no Alliance.

Parameters:

None

Returns:

The AllianceID string of the current Characters Alliance.

int

CBSampleImplementation::GetCurrentIntoxicationLevel()

Comments:

Sample function which should return a value representing how Drunk the current Character is.

Possible values include:

CB_INTOXICATION_NONE

CB_INTOXICATION_LIGHT

CB_INTOXICATION_MEDIUM

CB_INTOXICATION_HEAVY

ChatBlade shall use this information in order to determine how drastically to Intoxicate Chat Messages generated by a Drunk Character.

For use in Games which support Drinking.

Games without Drinking may hard-code the return value to be CB_INTOXICATION_NONE.

Parameters:

None

Returns:

CB_INTOXICATION_NONE for sober Characters.

CB_INTOXICATION_LIGHT for tipsy Characters.

CB_INTOXICATION_MEDIUM for Drunk Characters.

CB_INTOXICATION_HEAVY for very Drunk Characters.

int

CBSampleImplementation::GetLanguageKnowledgeLevel(

int nLanguageID)

Comments:

Sample function which returns the Level of proficiency in the target Language of the current Character.

Return values should range from 0 - 100 inclusive. Where 0 means the Character does not understand any of the Language, and 100 means the Character is fully fluent in the Language.

ChatBlade shall use this information to determine how drastically to Language Convert Chat Messages that are sent in an in-game artificial Language.

ChatBlade shall also use this information to determine what Languages a Character may change their default Language to using the /language Slash Command.

Game Developers should return a value from 0 - 100 representing how well the Character understands the target Language.

For use in Games which support in-game Languages such as Elvish, or Klingon. For Games with no Language Support this function should always return 100.

Parameters:

nLanguageID

The LanguageID of an in-game Language we want to check the Character knowledge of.

Returns:

A value from 0 - 100 representing the Character Knowledge of the LanguageID passed in.

int	CBSampleImplementation::GetLanguageString(	int nLanguageID /IN/,
		CBSTRING & sLanguageString /OUT/)

Comments:

Sample function which supplies a string value for a Language when given its ID.

Game Developers may want to alter this function to fit the Languages actually in their Game.

Parameters:

nLanguageID

The LanguageID of a Language for which we want to find the text String of.

sLanguageString

A reference to a string which shall contain the text representation of the Language, upon function return.

Returns:

Upon return sLanguageString should contain the text name of the Language, such as "Elvish".

CB_SUCCESS

int

CBSampleImplementation::IsDisplayableFaction(

int nFactionID)

Comments:

Sample function which should return CB_TRUE or CB_FALSE on whether Chat Messages of the supplied FactionID should be displayed based upon the FactionID, and the current Characters FactionID.

Chat Messages from opposing Factions should not be displayed, and this function should return CB_FALSE in those cases. Many PvP styled Games want to limit how much Players from opposing sides can communicate. This function is designed to limit such communication.

Game Developers should use their Game logic to determine if a Chat Message should be displayed by implementing this function.

This function is primarily designed with Faction Filtering in mind. For Games without Factions, this function should always return CB_TRUE.

If a Chat Message has no Faction or is from a Friendly or Neutral Faction this function should return CB_TRUE.

ChatBlade shall discard any Chat Messages where this function returns CB_FALSE.

Parameters:

nFactionID

A FactionID which we want to Faction Check to determine if Chat Messages from it should be Displayed or not.

Returns:

CB_FALSE if the FactionID is an opposing Faction and its Chat Messages should not be Displayed.

CB_TRUE if Chat Messages from the FactionID should be Displayed.

int

CBSampleImplementation::SendChatMessage(

CBChatMessage cbChatMessage)

Comments:

Sample function which passes a Chat Message off to the Networking Code for transmittal to a Chat Server.

A Chat Server should then forward the Chat Message onto other Players based on the Chat ChannelID and Destination found in the Chat Message.

This Sample invokes the Chat Sample Networking contained in CBChatSampleNetworkClient, which uses threads and Winsock to communicated with a Sample Chat Server.

Game Developers should implement this code to call their Networking Back End to pass a Chat Message to a Chat Server via the Network.

Parameters:

cbChatMessage

A Chat Message we want to send over the wire to the Chat Server for dispersal.

Returns:

CB_SUCCESS regardless of if a problem was encountered or not.

int

CBSampleImplementation::IsIgnorableCharacterName(

CBSTRING sCharacterName)

Comments:

This function should return whether or not a Character Name can be Ignored.

The Names of CSRs and GMs should be immune from being Ignored.

Game Developers should implement this function to compare the supplied Name vs. those of known Customer Service Representatives and GMs. If the Name matches a CSR or GM this function should return CB_FALSE.

This function should return CB_TRUE for most Player Character Names.

Called by CBIgnoreList::AddCharacter()

Parameters:

sCharacterName

A name of a Character that this Player wants to Ignore.

Returns:

CB_FALSE if the Name supplied is that of a CSR or GM employee.

CB_TRUE if the Name supplied is a normal Player Character Name.

int

CBSampleImplementation::ChatBubble(

CBChatMessage cbChatMessage)

Comments:

Function which allows the Game to display a Chat Bubble over a Characters head.

This function displays some of the logic which Chat Bubble implementation may invoke.

Not all Chat Channel Messages should have Chat Bubbles displayed, but the logic is left to the Game Developer.

ChatBlade supports Chat Bubbles by providing CBChatMessage::GetChatBubbleString() and by invoking this Stub when an incoming message is received.

Most of the implementation for Chat Bubbles is left to the Game Developer.

This function provides pseudo-code for implementing portions of Chat Bubble functionality.

Called by CBChatHandler::AddMessageToTextWindowDatas() via CBClientImplementation::ChatBubble().

Parameters:

cbChatMessage

A Chat Message that has been received by ChatBlade. May or may not be suitable for display in a Chat Bubble.

Returns:

CB_ERROR_NOT_IMPLEMENTED

int

CBSampleImplementation::ChatBeep(

CBChatMessage cbChatMessage)

Comments:

Function which demonstrates the Game performing an audio indicator on Incoming Chat.

Developers should determine which Chat Channels they want to make sounds for.

Preferably different Chat Channels would have differing sounds. This way a Player could receive an audio alert for Server messages that sounds distinct from that of normal Group Chat.

This function demonstrates how Chat Beeps can be implemented for incoming messages.

Called by CBChatHandler::OnIncomingChatMessage() via CBClientImplementation::ChatBeep().

Parameters:

cbChatMessage

A Chat Message received over the wire.

Returns:

CB_SUCCESS

int

CBSampleImplementation::DebugDisplayChatMessage(

CBChatMessage cbChatMessage)

Comments:

Function which displays the contents of a Chat Message.

This function invokes a Debug Display function in the related Sample MFC Test Client (CBMFCTestClient.exe) that shows the contents of all the fields in the Chat Message .

This function displays the contents of the latest Chat Message regardless of if any Chat Windows are Monitoring the Chat Channel the message came on.

Called by CBChatHandler::AddMessageToTextWindowDatas().

Parameters:

cbChatMessage

A Chat Message whose contents we want to display for Debug purposes.

Returns:

CB_SUCCESS

int

CBSampleImplementation::OnCommandExit(

)

Comments:

Function which exits the Sample application.

This function calls PostQuitMessage(0) to close the MFC Test Application.

Called by CBSlashCommands::OnCommandExit().

Parameters:

None

Returns:

CB_SUCCESS

Class	CBSampleImplementation
Header	CBSampleImplementation.h