ChatBlade SDK Documentation

Class   CBUtils
Header   CBUtils.h

Data    Member Summary    Member Details


Information 

CBUtils is a class designed to hold various Utility functions which are utilized by ChatBlade.  
String manipulation, Chat Intoxication, and Chat Message population are some of the functionality contained in this Class.  
 
All member functions of this class are Static and may be used Globally.  
As such, an instance of CBUtils does not need to be created.  
 

Game Developer Implementation:  

CBUtils does not need to be instantiated.  All members are Static.  
Developers may want to access its String manipulation functions.  
 

Source File Comments:  

// Represents a grouping of a variety of static members performing various utility functions
 
// Most of these functions involve string manipulation and are Unicode enabled
 

Data:  

None
        
 

Member Function Summary:  

            CBUtils()
        Empty Constructor.  
static int  CBStringToUpper(CBSTRING & sString /*IN OUT*/)
        Static function which modifies an incoming string and converts it to all UPPERCASE.  
static int  CBStringTrimLeft(CBSTRING & sString /*IN OUT*/)
        Static function which trims leading spaces off the front of a string.  
static int  CBStringTrimRight(CBSTRING & sString /*IN OUT*/)
        Static function which trims trailing spaces off the end of a string.  
static int  CBStringTrimEnds(CBSTRING & sString /*IN OUT*/)
        Static function which trims spaces off the front and back of a string.  
static int  CBStringIgnoreCompare(CBSTRING sStringA /*IN*/, CBSTRING sStringB /*IN*/)
        Returns 0 if the strings are =, <0 if sStringA is smaller and >0 if sStringA is larger.  Case insensitive.  
static int  CBStringIgnoreReplace(CBSTRING & sEntireString /*IN OUT*/, CBSTRING sOriginalString /*IN*/, CBSTRING sReplacementString /*IN*/)
        Static function which replaces all occurances of sOriginalString with sReplacementString in sEntireString.  Case insensitive.  
static int  CBStringRemovePunctuation(CBSTRING & sString /*IN OUT*/)
        Static function which modifies an incoming string and removes any punctuation from it.  
static int  CBStringGetFirstWord(CBSTRING & sFirstWord /*IN OUT*/, CBSTRING sEntireString /*IN*/)
        Static function which gets the first word of a string (space or end of string delimited).  
static int  CBStringSplitCommandLine(CBSTRING & sCommand /*OUT*/, CBSTRING & sFullLineOrParameters /*IN OUT*/)
        Static function which splits a command string into its / Command and parameters components.  
static int  CBStringSplitFirstWordFromLine(CBSTRING & sFirstWord /*OUT*/, CBSTRING & sFullLineOrParameters /*IN OUT*/)
        Static function which splits a string into its first word and the rest of the line components.  
static int  CBStringSplitLineAtComma(CBSTRING & sBeforeCommma /*OUT*/, CBSTRING & sFullLineThenAfterComma /*IN OUT*/)
        Static function which splits a string into 2 parts - the part before a comma and the part after the comma.  
static int  CBStringSplitLineAtTellDelimiter(CBSTRING & sTellDestination /*OUT*/, CBSTRING & sFullLineThenAfterDelimiter /*IN OUT*/)
        Static function which splits a string into 2 parts - the part before the Tell Character Name delimiter (comma or space usually) and the part after the delimiter.  
static int  CBStringRemoveLastLine(CBSTRING & sString /*IN OUT*/)
        Static function that removes the last newline and any text after it.  
static int  CBStringGetLastCharacter(TCHAR & cLastCharacter /*OUT*/, CBSTRING & sString /*IN*/)
        Static function that returns the last character of a string.  
static int  CBStringAddQuotes(CBSTRING & sString /*IN OUT*/)
        Static function that adds a pair of quotes to the beginning and the end of a string.  
static int  CBStringEnsureInitialSlash(CBSTRING & sString /*IN OUT*/)
        Static function that adds an initial Slash character to the beginning of the string if it does not already have one.   
static int  CBStringIntoxicateSpeech(CBSTRING & sString /*IN OUT*/, int nIntoxicationLevel /*IN*/)
        Static function that attempts to convert a line into its Drunken sounding equivalent.  
static int  CBStringIntoxicateWord(CBSTRING & sString /*IN OUT*/, int nIntoxicationLevel /*IN*/)
        Static function that attempts to convert a word into its Drunken sounding equivalent.  
static int  MakePlayerSentChatMessage(CBChatMessage & cbChatMessage /*IN OUT*/, CBSTRING sString /*IN*/, int nChannel /*IN*/, CBSTRING sDestination = CB_NONE /*IN*/)
        Static function that fills in the members of a reference to a CBChatMessage instance passed to it.  
static int  GetMoodStrings(int nMoodID /*IN*/, CBSTRING & sMoodString /*OUT*/, CBSTRING & sMoodAdverbString /*OUT*/)
        Static helper function which returns string values for the Mood given the MOODID.  
static int  IsAliasSlashCommand(CBSTRING sString )
        Static helper function which checks to make sure that  sString does not start with "/alias".  Used to prevent Aliasing the /alias Slash Command.  
static char *  DecodeReturnCode(int nReturnCode)
        Static debug function which converts ChatBlade return codes into readable strings.  
 

Member Function Detail:  

     CBUtils::CBUtils()  
Comments:
Empty Constructor.  
Parameters:
None
Returns:
None
 
static int  CBUtils::CBStringToUpper( CBSTRING & sString /*IN OUT*/)
Comments:
Static function which modifies an incoming string and converts it to all UPPERCASE.  
This function is Unicode enabled.  
ChatBlade stores most of its data in all UPPERCASE.  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit this parameter shall be converted to all UPPERCASE.  
Returns:
Upon exit the parameter shall be converted to UPPERCASE.  
CB_SUCCESS
 
static int  CBUtils::CBStringTrimLeft( CBSTRING & sString /*IN OUT*/)
Comments:
Static function which trims leading spaces off the front of a string.  
Removes any leading spaces which might be present in sString.  
Modifications are done in place.  
Parameters:
sString 
    A Reference to a CBSTRING.  Upon exit any initial spaces found in that string shall be removed.  
Returns:
Upon return sString shall have any leading spaces removed.  
CB_SUCCESS
 
static int  CBUtils::CBStringTrimRight( CBSTRING & sString /*IN OUT*/)
Comments:
Static function which trims trailing spaces off the end of a string.  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit any spaces found at the end of the string are removed.  
Returns:
Upon return sString shall have any trailing space characters removed.  
CB_SUCCESS
 
static int  CBUtils::CBStringTrimEnds( CBSTRING & sString /*IN OUT*/)
Comments:
Static function which trims spaces off the front and back of a string.  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit, any leading or trailing spaces found in the string shall be removed.  
Returns:
Upon return sString shall not start or end with a space character.  
CB_SUCCESS
 
static int  CBUtils::CBStringIgnoreCompare( CBSTRING sStringA /*IN*/,
    CBSTRING sStringB /*IN*/)
Comments:
Static function which compares 2 string and sees if they are equal.  
Returns 0 if the strings are =, <0 if sStringA is smaller and >0 if sStringA is larger.  
This function is not Case Sensitive and any Case is ignored in the string compare.  
Any leading or trailing spaces found in the strings is also ignored.  
Primarily used by ChatBlade to compare Slash Command parameters against known valid values.  
Parameters:
sStringA 
    A string to compare.  If this parameter is the same as sStringB, this function returns 0.  
sStringB 
    A string to compare against sStringA.  Case is ignored in the comparison.  
Returns:
0    if sStringA is the same as sStringB (Case insensitive).  
<0 if sStringA is smaller than sStringB.  
>0 if sStringA is larger than sStringB.  
 
static int  CBUtils::CBStringIgnoreReplace( CBSTRING & sEntireString /*IN OUT*/,
    CBSTRING sOriginalString /*IN*/,
    CBSTRING sReplacementString /*IN*/)
Comments:
Static function which goes through sEntireString and replaces any occurances of sOriginalString with sReplacementString.  
This function is not Case Sensitive and Case is ignored.  
Primarily used by ChatBlade to implement the core functionality of the CBReplacementFilter class.  
Parameters:
sEntireString 
    A reference to a CBSTRING to search through looking for phrases to replace.  Upon exit any occurances of sOriginalString shall be replaced with sReplacementString.  
sOriginalString 
    A string whose occurances shall be replaced in sEntireString.  Case is ignored.  Can be longer than 1 word.  
sReplacementString 
    A string with which to replace sOriginalString if it is found.  
Returns:
Upon return sEntireString shall have any occurances of sOriginalString replaced with sReplacementString.  
CB_SUCCESS
 
static int  CBUtils::CBStringRemovePunctuation( CBSTRING & sString /*IN OUT*/)
Comments:
Static function which modifies an incoming string and removes any punctuation from it.  
All !,. and other punctuation should be removed upon function return.  
This function is Unicode enabled.  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit any punctuation found in the string should be removed.  
Returns:
Upon return, sString should be altered to have any punctuation found in it eliminated.  
CB_SUCCESS
 
static int CBUtils::CBStringGetFirstWord( CBSTRING & sFirstWord /*IN OUT*/,
    CBSTRING sEntireString /*IN*/)
Comments:
Static function which gets the first word of a string (space or end of string delimited).  
Upon return sFirstWord should contain the first word found in a string.  sEntireString is not altered.  
Parameters:
sFirstWord 
    A reference to a CBSTRING.  Upon exit this parameter should be filled with the first word found in sEntireString.  
sEntireString 
    A string from which we want to find the first word.  Not modified by this function.  
Returns:
Upon return sFirstWord should contain the first word found in sEntireString.  
CB_ERROR_EMPTY_STRING if sEntireString is empty or contains only spaces.  
CB_SUCCESS
 
static int CBUtils::CBStringSplitCommandLine( CBSTRING & sCommand /*OUT*/,
    CBSTRING & sFullLineOrParameters /*IN OUT*/)
Comments:
Static function which splits a command string into its / Command and parameters components.  
This function is used by ChatBlade to separate a Player typed line of text into its Slash Command and Parameters components.  
Upon entry sFullLineOrParameters shall contain the full typed command containing both the Slash Command and its parameters.  
Upon exit sFullLineOrParameters shall only contain the parameters (if any) and shall have the initial Slash Command removed.  
Upon exit sCommand should contain the Slash Command portion of the line.  
For Example:  
    Upon Entry sFullLineOrParameters might = "/tell Irridia, Hi!"
    Upon Exit sFullLineOrParameters would = "Irridia, Hi!"
    Upon Exit sCommand  would = "/tell"
Parameters:
sCommand 
    A reference to a CBSTRING.  Upon exit this parameter should contain the Slash Command component found in the line.  
sFullLineOrParameters 
    A reference to a CBSTRING.  Initially this string contains both the Slash Command and any parameters.  Upon exit this variable should contain only the parameter portions of the string, if any.  
Returns:
Upon return sCommand should contain the Slash Command.  
Upon return sFullLineOrParameters should have the initial Slash Command removed.  
CB_ERROR_EMPTY_STRING if sFullLineOrParameters is empty or contains only spaces.  
CB_SUCCESS
 
static int  CBUtils::CBStringSplitFirstWordFromLine( CBSTRING & sFirstWord /*OUT*/,
    CBSTRING & sFullLineOrParameters /*IN OUT*/)
Comments:
Static function which splits a string into its first word and the rest of the line components.  
Upon entry sFullLineOrParameters should contain the full line with all the words.  
Upon exit sFirstWord contains the first word and sFullLineOrParameters should contain only the parameters with the first word removed.  
This function removes the first word found in sFullLineOrParameters and places it into sFirstWord.  
Parameters:
sFirstWord 
    A reference to a CBSTRING.  Upon exit this parameter should contain the first word found in the line.  
sFullLineOrParameters 
    A reference to a CBSTRING.  Upon exit this variable should have its first word removed.  
Returns:
Upon return sFirstWord should contain the first word found in sFullLineOrParameters.  
Upon return sFullLineOrParameters should have the first word removed.  
CB_ERROR_EMPTY_STRING if sFullLineOrParameters is empty or contains only spaces.  
CB_SUCCESS
 
static int  CBUtils::CBStringSplitLineAtComma( CBSTRING & sBeforeCommma /*OUT*/,
    CBSTRING & sFullLineThenAfterComma /*IN OUT*/)
Comments:
Static function which splits a string into 2 parts - the part before a comma and the part after the comma.  
The comma and any spaces around the comma are removed.  
Leading and trailing spaces on the 2 line parts are also removed.  
If the string has no comma the entire string is placed into sBeforeCommma.  
Upon entry sFullLineThenAfterComma should contain the full line with all the words.  
Upon exit sBeforeCommma contains the text before the first comma and sFullLineThenAfterComma should contain the text after the first comma.  
Parameters:
sBeforeCommma 
    A reference to a CBSTRING.  Upon exit this parameter should contain the portion of the line that is before the first comma character found.    
sFullLineThenAfterComma 
    A reference to a CBSTRING.  Upon exit this variable should contain the portions after the first comma.  Any trailing spaces are also removed.  
Returns:
Upon return sBeforeCommma contains the portion of the string that is before the first comma found.  
Upon return sFullLineThenAfterComma contains the portion of the string after the first comma found.  
CB_SUCCESS
 
static int  CBUtils::CBStringSplitLineAtTellDelimiter( CBSTRING & sTellDestination /*OUT*/,
    CBSTRING & sFullLineThenAfterDelimiter /*IN OUT*/)
Comments:
Static function which splits a string into 2 parts - the part before the Tell Character Name delimiter (comma or space usually) and the part after the delimiter.  
This function is used by ChatBlade to find the name of a Character when one sends a /Tell.  
Games with only single word Character names use a space (' ') as the delimiter to tell when a Character name has ended.  
Games that allow multi-word Character names can contain spaces in the name.  In these cases ChatBlade typically shall use a comma (',') as the delimiter to determine when a Character name has ended.  
This value is defined in CBConstants.h as CB_CHARACTER_NAME_DELIMITER.  
Upon entry sFullLineThenAfterDelimiter should contain the Character name and any text to tell that Character.  
Upon exit sTellDestination should contain the Character name and it should be removed from sFullLineThenAfterDelimiter.  
The delimiter and any spaces around the delimiter are removed.  
Leading and trailing spaces on the 2 line parts are also removed.  
If the string has no delimiter the entire string is placed into sTellDestination.  
Parameters:
sTellDestination 
    A reference to a CBSTRING.  Upon exit this parameter should contain the name of a Character that is initially found as the first part of sFullLineThenAfterDelimiter.  
sFullLineThenAfterDelimiter 
    A reference to a CBSTRING.  Upon exit this variable should contain the portions after the initial Character name.  Any trailing spaces are also removed.  
Returns:
Upon return sTellDestination should contain the Character name found in sFullLineThenAfterDelimiter.  
Upon return sFullLineThenAfterDelimiter should have the initial Character name removed.  
CB_SUCCESS
 
static int  CBUtils::CBStringRemoveLastLine( CBSTRING & sString /*IN OUT*/)
Comments:
Static function that removes the last newline and any text after it.  
Shall not remove the first line of text if no newline is found
Used by ChatBlade to remove any trailing Newline typically.  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit this parameter shall have the last Newline found removed, and any text after the last Newline deleted.  
Returns:
Upon return sString shall have its last line of text removed unless there is only 1 line of text.  
CB_SUCCESS
 
static int  CBUtils::CBStringGetLastCharacter( TCHAR & cLastCharacter /*OUT*/,
    CBSTRING  sString /*IN*/)
Comments:
Static function that supplies the last character of a string.  
If the string was "Hi!" this function would fill in cLastCharacter with '!'.  
Ending white space is ignored.   
Parameters:
cLastCharacter 
    A reference to a character which shall hold the last character found in sString that is not a space.  
sString 
    A CBSTRING to find the last character of.  
Returns:
Upon return cLastCharacter shall be the last character found in sString or '' (empty character) if sString is too short or only contains spaces.    
CB_ERROR_EMPTY_STRING if sString contains no non-space characters or is empty.  
CB_SUCCESS
 
static int  CBUtils::CBStringAddQuotes( CBSTRING & sString /*IN OUT*/)
Comments:
Static function that adds a pair of quotes to the beginning and the end of a string.  
Used by ChatBlade to add quotes around spoken style Chat Channel messages.  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit this parameter shall be surrounded by quotes.  
Returns:
Upon return sString shall have quotes prepended and appended onto it.  
CB_SUCCESS
 
static int  CBUtils::CBStringEnsureInitialSlash( CBSTRING & sString /*IN OUT*/)
Comments:
Static function which makes sure that the passed in parameter starts with a Slash character (CB_SLASHCOMMAND_CHARACTER) upon function return.  
If sString does not begin with a '/' then then function shall add one to it, at the beginning.  
If sString does start with a Slash character, then sString is left as it is.  
Called by CBCommandMap::AddAlias() and CBSlashCommands::OnCommandChatHelp().  
Parameters:
sString 
    A reference to a CBSTRING.  Upon exit this parameter shall be guaranteed to start with a '/' (unless it is an empty string).  
Returns:
Upon return sString shall start with CB_SLASHCOMMAND_CHARACTER.  
CB_ERROR_EMPTY_STRING if sString is empty.  
CB_SUCCESS whether or not a Slash character was already present or was added.  
 
static int  CBUtils::CBStringIntoxicateSpeech( CBSTRING & sString /*IN OUT*/,
    int nIntoxicationLevel /*IN*/)
Comments:
Static function that attempts to convert a line into its Drunken sounding equivalent.  
Used for Games which support Drinking.  
Replaces letters in words with ones drunks might use based upon the level of drunkenness.  
The code provided in this function is mostly sample code and should be altered to fit the Game Developers aesthetics.  
This function is designed to support English only, though most western Character sets should work fine.  
The degree with which the text is altered is dependant upon the level of Intoxication.  
ChatBlade supports 4 levels of Intoxication: CB_INTOXICATION_NONE, CB_INTOXICATION_LIGHT, CB_INTOXICATION_MEDIUM, and CB_INTOXICATION_HEAVY.  
If the Intoxication level is CB_INTOXICATION_NONE, sString remains unaltered.  
Any HyperLinks found in the string are not Intoxicated.  
Characters who are drunk have their typed Chat altered by ChatBlade using this function.  
Parameters:
sString 
    A reference to a CBSTRING.  Initially a normal line of Chat typed by a Player.  Upon exit this parameter is altered to support slurred style drunken speech, if the Character is Intoxicated.  
nIntoxicationLevel 
    A value representing one of the 4 supported levels of Intoxication.  
Returns:
Upon return sString shall be slurred based on nIntoxicationLevel.  
CB_SUCCESS
 
static int  CBUtils::CBStringIntoxicateWord( CBSTRING & sString /*IN OUT*/,
    int nIntoxicationLevel /*IN*/)
Comments:
Static function that attempts to convert a word into its Drunken sounding equivalent.  
Used for Games which support Drinking.  
Replaces letters in words with ones drunks might use based upon the level of drunkenness.  
The code provided in this function is mostly sample code and should be altered to fit the Game Developers aesthetics.  
This function is designed to support English only, though most western Character sets should work fine.  
The degree with which the text is altered is dependant upon the level of Intoxication.  
ChatBlade supports 4 levels of Intoxication: CB_INTOXICATION_NONE, CB_INTOXICATION_LIGHT, CB_INTOXICATION_MEDIUM, and CB_INTOXICATION_HEAVY.  
If the Intoxication level is CB_INTOXICATION_NONE, sString remains unaltered.  
Parameters:
sString 
    A reference to a CBSTRING.  Initially a word typed by a Player.  Upon exit this parameter is altered to support slurred style drunken speech, if the Character is Intoxicated.  
nIntoxicationLevel 
    A value representing one of the 4 supported levels of Intoxication.  
Returns:
Upon return sString shall be slurred based on nIntoxicationLevel.  
CB_SUCCESS
 
static int  CBUtils::MakePlayerSentChatMessage( CBChatMessage & cbChatMessage /*IN OUT*/,
    CBSTRING sString /*IN*/,
    int nChannel /*IN*/,
    CBSTRING sDestination = CB_NONE /*IN*/)
Comments:
Static function that fills in the members of a reference to a CBChatMessage instance passed to it.  
Uses the Characters current Name, Mood, Language, and Faction settings.  
This function fills in the members of cbChatMessage.  It uses values from CBData and calls functions in CBClientImplementation to get the Characters Name, Mood, Language and Faction settings.  
Any information initially in cbChatMessage is overwritten.   
The Timestamp value of the Chat Message is not set.  
sDestination defaults to CB_NONE.  
Used by ChatBlade to populate a CBChatMessage instance using data from the current Character.  
Parameters:
cbChatMessage 
    A reference to a CBChatMessage instance.  Upon exit this parameter should have its data values filled.  
sString 
    The text payload that should be in the CBChatMessage.  Typically typed Chat created by the Player.  
nChannel 
    The Chat ChannelID of the Chat Message.  For Example:  CB_CHANNEL_SAY, or CB_CHANNEL_GROUP.  
sDestination 
    The Destination of the Chat Message.  Typically another Character Name for Tells, or a GroupID for Group Chat, etc.  
Returns:
Upon return cbChatMessage should have its data members filled in.  
CB_SUCCESS
 
static int  CBUtils::GetMoodStrings( int nMoodID /*IN*/,
    CBSTRING & sMoodString /*OUT*/,
    CBSTRING & sMoodAdverbString /*OUT*/)
Comments:
Static helper function which returns string values for the Mood given the MOODID.  
For Example:  If nMoodID = CB_MOOD_CHEERFUL, upon return sMoodString shall be "Cheerful" and sMoodAdverbString shall be "Cheerfully".  
Used by ChatBlade to support Moods in Chat Message formatting.  
If Game Developers want to add additional Moods to the Game, this function should be altered to support the new Moods.  
Parameters:
nMoodID 
    The MoodID for which we want to get text strings of.  For Example:  CB_MOOD_HAPPY.  
sMoodString 
    A reference to a string which shall contain the text representation of the MoodID.  For Example:  "Happy".  
sMoodAdverbString 
    A reference to a string which shall contain the adverb style text representation of the MoodID.  For Example:  "Happily".  
Returns:
Upon return sMoodString should contain the string representation of nMoodID.  
Upon return sMoodAdverbString should contain the adverb version of sMoodString.  
CB_SUCCESS
 
static int  CBUtils::IsAliasSlashCommand( CBSTRING  sString)
Comments:
Static helper function which checks to see if sString starts with the string "/ALIAS".  
Called by CBSlashCommands::OnCommandAlias() to make sure the Player is not attempting to Alias the /alias Slash Command.  
Used by ChatBlade to prevent Players from making Aliases from the existing /alias Slash Command.    
Parameters:
sString 
    A string to check to see if it starts with "/alias".    
Returns:
CB_TRUE if the first word found in sString is "/alias" (or any loaded Aliases of /alias).  
CB_FALSE if sString is not a Slash Command which invokes the function CBSlashCommands::OnCommandAlias().  
 
static char *  CBUtils::DecodeReturnCode( int nReturnCode)
Comments:
Static debug helper function which converts ChatBlade return codes into readable strings.  
Returns the string representation of a ChatBlade return value.  
This function is designed to assist in debugging.  
Parameters:
nReturnCode
    A ChatBlade return value.  
Returns:
A string representing the ChatBlade Return Code.  For Example:  "CB_ERROR_EMPTY_STRING" as a C string.  
 
 

 

 

 

ChatBlade Copyright Flex Dolphynn