ChatBlade SDK Documentation

Class   CBChatMessage
Header   CBChatMessage.h

Data    Member Summary    Member Details

Information:  

CBChatMessage is a class which represents a single Chat Message.  
It contains data members representing the Source, Destination, and Channel of the Chat Message, as well as an array of the Text of the message.  In addition this class contains functions to retrieve the Text and set the Verbosity (formatting) of the Chat Message.  
 
CBChatMessages are primarily stored in a Deque of a CBTextWindowData instance.  The CBTextWindowData class contains the array (deque) of Chat Messages a GUI Chat Window should display.  
 
CBChatMessage contains fields for the Mood, Language, and Faction of the Chat Message for games which support these features.  Other Fields such as a ShardID may be added depending on Game Design.  
Each CBChatMessage should end up with a timestamp.  For messages received over the wire the ChatBlade sample programs add the timestamp at the time the message was received by the client.  For local messages which do not go out over the Net, the timestamp should be set to when the message was created.  
 
ChatBlade currently supports 2 different types of message formats.  A Static function which applies to all Chat messages may be called to specify how the messages should be displayed.  Either call CBChatMessage::SetVerbosityLevel(), or call CBChatHandler::SetVerbosityLevel().  Players should be able to dynamically change between the message formats by using the Slash Command /verbose.  
 
To get the Text out of a CBChatMessage instance one may call GetChatString(),  GetChatStringWithHyperlinks(), or GetChatBubbleString().  All return the Chat Text including the text portion of any HyperLinks, but GetChatStringWithHyperlinks() also returns the HyperLink tag information which shall need to be removed by the GUI before display.  

Game Developer Implementation:  

CBChatMessage is the form that ChatBlade uses to store a Chat Message.  
The class provides fields for Source, Destination, Channel, Mood, Language, Faction, and Timestamp.  Not all games shall be designed to support Mood, Language, or Faction, so to save space these fields can be removed.  To remove the fields one shall need to go through the ChatBlade classes and manually delete references to those fields in the source files.  
Depending on Game Design a ShardID (ServerID) field may need to be added to this class.  
To get the Text out of a CBChatMessage instance one may call GetChatString() or GetChatStringWithHyperlinks().  Both return the Chat Text including the text portion of any HyperLinks, but the latter function also returns the HyperLink tag information which shall need to be removed by the GUI before display.  GetChatBubbleString() may be called to get text suitable for display in a Chat Bubble.  
The Text of the Chat Message is stored into an array called vMessagePartsArray.  If the messages contains no HyperLinks this array has a size of 1 representing all the text.  If the message does contain HyperLinks the array is split up so that the HyperLinks are separate entries in the array.   
CBUtils::MakePlayerSentChatMessage() can be used to fill in a CBChatMessage instance before a Chat Message is sent over the wire.  
CBChatHandler::AddGenericMessage() and related functions take the message parameters then create and process a internal CBChatMessage instance representing a local Chat Message for display in the Game Client.  

Source File Comments:  

// CBChatMessage represents a single chat message
// This Class contains the Source, Destination, Channel, Message Text and other information associated with the Message
// For received messages the Timestamp of the message is the time it was received from the wire not the time it was sent
// For messages which do not go out on the wire the Timestamp is the time the message was generated

Data:  

static int m_nVerbosityLevel
        Determines how Chat Messages should be formatted.  Global to all CBChatMessage instances.
         CB_VERBOSITY_CONCISE or CB_VERBOSITY_VERBOSE.  
CBSTRING sSource
        Typically the name of the Character creating this Chat Message.  CB_NONE if there is no Source.  
CBSTRING sDestination
        Destination name for the Chat Message.  Typically a Player Name, GroupID, GuildID, etc.  CB_NONE if inapplicable.  
int nChannelID
        The Chat Channel the message is destined for.  Examples:  CB_CHANNEL_TELL, CB_CHANNEL_GROUP, or CB_CHANNEL_AUCTION.  
int nMoodID
        The Mood the message was created in.  Examples:  CB_MOOD_HAPPY, CB_MOOD_CHEERFUL, or CB_MOOD_NONE.  For use in Games which support Moods.    
int nLanguageID
        The in-game Language the message was created in.  Examples:  CB_LANGUAGE_ELVISH, CB_LANGUAGE_ORCISH, CB_LANGUAGE_NONE.  For use in Games which support Languages.  
int nFactionID
        The Faction of the originating Character.  Examples: CB_FACTION_GOOD,  CB_FACTION_NEUTRAL, or CB_FACTION_NONE.  For Games which use Factions.  
time_t tTimeStamp
        The Timestamp of when the message was Received or when it was Created (for local only messages).  
std::vector<CBSTRING> vMessagePartsArray
        An Array of the Text parts of a Message.  The array is split to place any HyperLinks as their own entry in the array.  For messages with no Hyperlinks this array has a size of 1.  
 

Member Function Summary:  

                 CBChatMessage()
        Constructor.  
                 CBChatMessage(const CBChatMessage & cbcmChatMessage)
        Copy Constructor.  
int              ClearMessage()
        Sets all Data fields to their NONE value and clears out vMessagePartsArray.  
int              MakeMessagePartsArray(CBSTRING sRawStringPayload)
        Fills in the vMessagePartsArray from the supplied parameter.  
CBChatMessage &  operator=(const CBChatMessage & cbcmChatMessage)
        Assignment operator.  
static int       SetVerbosityLevel(int nVerbosityLevel)
        Static function used to set the Chat Message Display format.  
int              GetChatStringWithHyperlinks(CBSTRING & sChatString /*OUT*/)
        Fills in the parameter with the complete text of the Chat Message, including the Source, Channel, and any Hyperlink Tags.  
int              GetChatString(CBSTRING & sChatString /*OUT*/)
        Fills in the parameter with the complete text of the Chat Message, including the Source, Channel, but excludes any HyperLink Tag elements, while including the HyperLink text.  
int              GetChatBubbleString(CBSTRING & sChatString /*OUT*/)
        Fills in the parameter with the text suitable for display in a Chat Bubble.  No Source, Channel, Mood, or Hyperlink Tags are included.  
int               GetRawChatString(CBSTRING & sChatString /*OUT*/)
        Fills in the parameter with the raw Text of the Chat Message including the Source, Channel, Mood, and Language.  No Chat Filtering or Language conversion is done to the text.  Hyperlink text is included but not Hyperlink tags.  
int               GetConfigurableChatString(CBSTRING & sChatString /*OUT*/, int bGetBeginningFlag /*IN*/, int bGetHyperlinkTagsFlag /*IN*/, int bLanguageConvertFlag /*IN*/, int bFilterTextFlag /*IN*/, int bBoundMessageFlag /*IN*/)
        Fills in sChatString with the Text of the Chat Message.  The parameters passed in determine the portions included and filters to use on the Chat Text.  
int              GetChannelSourceStringBeginning(CBSTRING & sChatBeginning /*OUT*/)
        Helper function which fills in the formatted Source, Channel, and Mood, and Language of the Chat Message.  
int                GetMessageDataStrings(CBSTRING & sSourceString /*OUT*/, CBSTRING & sDestinationString /*OUT*/, CBSTRING & sMoodString /*OUT*/, CBSTRING & sMoodAdverbString /*OUT*/, CBSTRING & sLanguageString /*OUT*/, int & bIsSourceYou /*OUT*/)
        Helper function which fills in the Source, Destination, Mood, and Language of the Chat Message.  
int               GetMessageMoodStrings(CBSTRING & sMoodString /*OUT*/, CBSTRING & sMoodAdverbString /*OUT*/)
        Helper function which fills in the messages Mood strings based on the MoodID.  
int               GetMessageLanguageString(CBSTRING & sLanguageString /*OUT*/)
        Helper function which fills in the Language the Message is in based upon the LanguageID.  
int               GetMessageVerbString(CBSTRING & sVerbString /*OUT*/, int bIsSourceYou /*IN*/)
        Helper function which returns a verb string used for Verbose Chat (such as "Asks", or "Says").  
int               BoundMessageText(CBSTRING & sString /*IN OUT*/)
        Helper function which adds Quotes around Message on certain spoken channels.  
int               IsChatHyperlinked()
        Helper function which returns CB_TRUE if the text of this instance contains a Hyperlink.  
int               IsLanguageConvertibleText()
        Helper function which returns CB_TRUE if the text should be subject to potential Language Conversion (Elvish, etc.).   
 

Member Function Detail:  

     CBChatMessage::CBChatMessage()
Comments:
Constructor which calls ClearMessage().  
Parameters:
None
Returns:
None
 
     CBChatMessage::CBChatMessage( const CBChatMessage & cbcmChatMessage)
Comments:
Copy Constructor.  
Copies each element of the Parameter over into this CBChatMessage instance.  
Parameters:
cbcmChatMessage
    A CBChatMessage instance whose data we want to copy.  
Returns:
None
 
int  CBChatMessage::ClearMessage()
Comments:
Sets all the data members to their None value such as setting the nMoodID to CB_MOOD_NONE, etc.  Sets the TimeStamp to 0.  Clears out any data in the vMessagePartsArray.  
Parameters:
None
Returns:
CB_SUCCESS
 
int  CBChatMessage::MakeMessagePartsArray( CBSTRING sRawStringPayload)
Comments:
Takes the raw text of a Chat Message and fills in the vMessagePartsArray with it.  
Makes sure that each Hyperlink in the message is its own entry into the Array.  
For messages with no Hyperlinks the size of the array is 1.  
Parameters:
sRawStringPayload
    The Text of the chat message including any Hyperlinks, but not including the Source or Destination.  
Returns:
CB_SUCCESS
 
CBChatMessage &  CBChatMessage::operator=( const CBChatMessage & cbcmChatMessage)
Comments:
Assignment Operator to copy an existing CBChatMessage instance into a new Instance.  
Copies all the data from the parameter, over into this instance.  
Parameters:
cbcmChatMessage
    An existing CBChatMessage instance we want to copy.  
Returns:
A reference to this instance via (*this).  
 
static int  CBChatMessage::SetVerbosityLevel( int nVerbosityLevel)
Comments:
Static function which sets how all the Chat Message are to be displayed.  
ChatBlade currently supports 2 types of message formatting, CB_VERBOSITY_CONCISE, and CB_VERBOSITY_VERBOSE.  
Developers may alternately call CBChatHandler::SetVerbosityLevel().  
Players can typically use the /verbose Slash Command to set how they want their Chat Messages displayed.  
Examples of the 2 Formatting types:  
  CB_VERBOSITY_CONCISE:  
    [Group] You: Lets hunt in Vortopolis.  
    [Say] Happy, Elvish, You, "Anyone want some Lambas?"  
  CB_VERBOSITY_VERBOSE:  
    You Tell the Group: Lets hunt in Vortopolis.  
    You Say Happily in Elvish, "Anyone want some Lambas?"  
Parameters:
nVerbosityLevel
    The verbosity Setting.  CB_VERBOSITY_CONCISE or CB_VERBOSITY_VERBOSE.  
Returns:
CB_SUCCESS
 
int  CBChatMessage::GetChatStringWithHyperlinks( CBSTRING & sChatString /*OUT*/)
Comments:
Gets the Chat Message as a string.  
Fills in the parameter with the formatted Chat Message contained in this instance.  All parts of the message are included, including the Source, Channel, and full HyperLinks including any HyperLink tags.  If the message contains a Mood or Language these portions are included as well.  
Since the sChatString may contain HyperLink tags the GUI should remove any tags before displaying the Chat Message.  
This function is designed to be called by the Game in order to get the text from a CBChatMessage instance.  
Examples of the resulting strings:  
    You Say, "Anyone want to Group?"
    [Auction] Vanadia:  href=12BA4C<Thunder Sword> 10000 gold.  
Offensive words in the Chat String may be filtered if the Chat Filter is enabled.  If the Chat Message is not in a Language the Character is fully fluent in the the Chat String may be subject to Language Conversion.  
Parameters:
sChatString 
    A reference to a String which shall hold the text representing the Chat Message upon return.  Any HyperLink tags in the message are included.  
Returns:
CB_SUCCESS
Upon function return sChatString is filled with the formatted Text representing this Chat Message.  
 
int  CBChatMessage::GetChatString( CBSTRING & sChatString /*OUT*/)
Comments:
Gets the Chat Message as a string.  
Fills in the parameter with the formatted Chat Message contained in this instance.  Most parts of the message are included, including the Source, Channel, and the HyperLink Text.  Any internal HyperLink tags are left out of the Message.  If the message contains a Mood or Language these portions are included as well.  
HyperLink tags are removed, while the HyperLink text is retained.  
This function is designed to be called by the Game in order to get the text from a CBChatMessage instance.  
Examples of the resulting strings:  
    You ask, "Anyone want to Group?"
    [Auction] Vanadia:  Thunder Sword 10000 gold.  
Offensive words in the Chat String may be filtered if the Chat Filter is enabled.  If the Chat Message is not in a Language the Character is fully fluent in the the Chat String may be subject to Language Conversion.  
Parameters:
sChatString 
    A reference to a String which shall hold the text representing the Chat Message upon return.  Any HyperLink tags in the message are removed.  
Returns:
CB_SUCCESS
Upon function return sChatString is filled with the formatted Text representing this Chat Message.  
 
int  CBChatMessage::GetChatBubbleString( CBSTRING & sChatString /*OUT*/)
Comments:
Gets the Chat Message as a string suitable for display in a Chat Bubble above a Characters head.  
Fills in the parameter with the formatted Chat Message contained in this instance.  Only the text payload of the Chat Message is included.  The Source, Chat Channel, Mood and any Hyperlink tags are excluded and should not be displayed in Chat Bubbles.  
HyperLink tags are removed, while the HyperLink text is retained, making this function suitable to obtaining Chat that should be displayed in a Chat Bubble that does not need to include Linking.  
This function is designed to be called by the Game in order to get the text from a CBChatMessage instance.  
Examples of the resulting strings:  
    Anyone want to Group?
    Thunder Sword 10000 gold.  
Offensive words in the Chat String may be filtered if the Chat Filter is enabled.  If the Chat Message is not in a Language the Character is fully fluent in the the Chat String may be subject to Language Conversion.  
Parameters:
sChatString 
    A reference to a String which shall hold the text representing the Chat Message upon return.  Any HyperLink tags in the message are removed and Source, Channel, and Mood are not included.  
Returns:
CB_SUCCESS
Upon function return sChatString is filled with the formatted Text representing this Chat Message.  
 
int  CBChatMessage::GetRawChatString( CBSTRING & sChatString /*OUT*/)
Comments:
Gets the Chat Message as a string with no Chat Filtering or Language Conversion performed.  
Fills in the parameter with the formatted Chat Message contained in this instance.  Most parts of the message are included, including the Source, Channel, and the HyperLink Text.  Any internal HyperLink tags are left out of the Message.  If the message contains a Mood or Language these portions are included as well.  
HyperLink tags are removed, while the HyperLink text is retained.  
This function is designed to be called by the Spam Filter in order to determine whether the Chat Message contains Spam and should be blocked.  
Examples of the resulting strings:  
    You ask, "Anyone want to Group?"
    [Auction] Vanadia:  Thunder Sword 10000 gold.  
Parameters:
sChatString 
    A reference to a String which shall hold the text representing the Chat Message upon return.  Any HyperLink tags in the message are removed.  
Returns:
CB_SUCCESS
Upon function return sChatString is filled with the formatted Text representing this Chat Message.  
 
int  CBChatMessage::GetConfigurableChatString( CBSTRING & sChatString /*OUT*/,
    int bGetBeginningFlag /*IN*/,
    int bGetHyperlinkTagsFlag /*IN*/,
    int bLanguageConvertFlag /*IN*/,
    int bFilterTextFlag /*IN*/,
    int bBoundMessageFlag /*IN*/)
Comments:
Helper function which gets the Chat Message as a string.  The flags passed in determine what parts to include in the string and how they are filtered and modified.    
Fills in sChatString with the formatted Chat Message contained in this instance.  Which parts of the Chat Message to include and how to format them are dependent upon the settings of the Flag parameters which are passed in.  
Hyperlink Tags, the Chat Beginning (source, mood, language, channel), and Quotes can be optionally left off the message.   
Language Conversion (to Elvish or other in-game Languages) and Chat Filtering (to block bad words) may be optionally enabled or disabled.   
Examples of the resulting strings:  
    You ask, "Anyone want to Group?"
    [Auction] Vanadia:  Thunder Sword 10000 gold.  
    [Auction] Vanadia:  href=12BA4C<Thunder Sword> 10000 gold.  
    You say in Elvish, Tinah Adene Nav Ylena
    Anyone want to Group?
Called by the various other GetChatStringXXX() functions.  
Parameters:
sChatString 
    A reference to a String which shall hold the text representing the Chat Message upon return.  
bGetBeginningFlag
    A flag indicating whether or not to include the Source, Channel, Mood, and Language of the Chat Message at the beginning of the returned string.  
bGetHyperlinkTagsFlag
    A flag indicating whether or not to include the Hyperlink Tags (href=IT3M1D) with the Hyperlink text.  
bLanguageConvertFlag
    A flag indicating whether or not to perform potential Language Conversion of the Chat Message.  
bFilterTextFlag
    A flag indicating whether or not to potentially filter out bad words from the Chat Message.  
bBoundMessageFlag
    A flag indicating whether or not to potentially bound the Chat Message in quotes.  
Returns:
CB_SUCCESS
Upon function return sChatString is filled with the formatted Text representing this Chat Message.  
 
int  CBChatMessage::GetChannelSourceStringBeginning( CBSTRING & sChatBeginning /*OUT*/)
Comments:
Helper function which obtains the formatted beginning portions of this Chat Message including the Source, Channel, Mood, and Language, but excludes any of the message Text.  
Examples include:  
    [Group] Vanadia:
   Vanadia Says Happily,
Called by GetChatStringWithHyperlinks() and GetChatString().  
Parameters:
sChatBeginning 
    A reference to a String which shall represent the beginning portion of the Chat Message (all parts before the chat Text) upon function return.  
Returns:
CB_SUCCESS
Upon return sChatBeginning shall be filled with the formatted initial portion of the Chat Message.  
 
int  CBChatMessage::GetMessageDataStrings( CBSTRING & sSourceString /*OUT*/,
CBSTRING & sDestinationString /*OUT*/,
CBSTRING & sMoodString /*OUT*/,
CBSTRING & sMoodAdverbString /*OUT*/,
CBSTRING & sLanguageString /*OUT*/,
int & bIsSourceYou /*OUT*/)
Comments:
Fills in the Parameters with the string representations of information stored in this CBChatMessage instance.  
Retrieves the Mood string in both normal and Adverb versions.  
If the Source of the message is this Player then the sSourceString is set to be "You" and bIsSourceYou is set to TRUE.  If the Destination of the Message is the Player the sDestinationString is set to be "You".  
Examples:  
    sSourceString can be filled with Vanadia or You (if this Player is Vanadia).  
    sDestinationString can be filled with Irridia or You (if this Player is Irridia).  
    sMoodString might by Happy.  
    sMoodAdverbString might be Happily.  
    sLanguageString might be Elvish.  
Helper function called by GetChannelSourceStringBeginning().  
Parameters:
sSourceString 
    A reference to a string which shall contain the Source of the message upon function return.  
sDestinationString 
   A reference to a string which shall contain the Destination of the message upon function return.   
sMoodString 
    A reference to a string which shall contain the Mood of the message upon function return.  
sMoodAdverbString 
    A reference to a string which shall contain the Mood as an adverb upon function return.  
sLanguageString 
   A reference to a string which shall contain the Language of the message upon function return.   
bIsSourceYou 
    A reference to a Flag which shall indicate if the Source of the Chat Message is this Player.  
Returns:
CB_SUCCESS
Upon return the parameters of this function are filled with their appropriate values.  
 
int  CBChatMessage::GetMessageMoodStrings( CBSTRING & sMoodString /*OUT*/,
CBSTRING & sMoodAdverbString /*OUT*/)
Comments:
Helper function which gets the String representation of the Mood of the Chat Message.  
Fills in both a normal string of the Mood as well as the adverb version of that Mood.  
Called by GetMessageDataStrings().  
See CBUtils::GetMoodStrings().  
Parameters:
sMoodString 
    A reference to a String which shall hold the Mood of the Chat Message upon function return.  
sMoodAdverbString 
    A reference to a String which shall hold the adverb version of the Mood of the Chat Message upon function return.   
Returns:
CB_SUCCESS
Upon function return the parameters should contain the text values of the Mood of this Chat Message.  
 
int  CBChatMessage::GetMessageLanguageString( CBSTRING & sLanguageString /*OUT*/)
Comments:
Helper function which returns a string representing the LanguageID of the Chat Message.  
Example:  
    Elvish
Called by GetMessageDataStrings().  
See CBClientImplementation::GetLanguageString().  
Parameters:
sLanguageString 
    A reference to a String which shall hold the text representation of the Language the message was sent in.  
 
Returns:
CB_SUCCESS
Upon return sLanguageString shall contain the text representation of the Chat Message LanguageID.  
 
int  CBChatMessage::GetMessageVerbString( CBSTRING & sVerbString /*OUT*/, 
    int bIsSourceYou /*IN*/)
Comments:
Helper function which returns a verb string used for Verbose Chat.   
This function looks to see if the Chat Message is a Question, an Exclamation, or neither.  It returns the proper verb to use based on if the Source is the current User and if the Chat Message is a Statement, Question, or Exclamation.  
sVerbString is set to be "Tell", "Tells", "Say", "Says", 'Ask", "Asks", "Exclaim", "Exclaims", "Exclaim to", or "Exclaims to".  
If a Chat Message ends in a ? then "Ask" or "Asks" is used (depending on the value of bIsSourceYou ).  An exclamation point (!) causes the verb to be one of the "Exclaim" variants.  
So, by using this functionality ChatBlade can format Verbose Chat to display:  
     Vanadia Asks, "Anyone need my Levin Sword?"  
instead of:  
    Vanadia Says, "Anyone need my Levin Sword?"  
Called by CBChatMessage::GetChannelSourceStringBeginning().  
Parameters:
sVerbString 
    A reference to a String which, upon return, shall hold the correct verb to use depending on if the Chat Message is a Statement, Question, or Exclamation.  
bIsSourceYou 
    A flag representing if the Source of the Chat Message is the current Player.  
 
Returns:
CB_SUCCESS
Upon return sVerbString shall contain the verb to use when displaying this Chat Message in Verbose mode.  
 
int  CBChatMessage::BoundMessageText( CBSTRING & sString /*IN OUT*/)
Comments:
Helper function which surrounds the text of spoken type Chat Messages with Quotes.  
In order to show Messages on spoken Chat Channels more pleasingly spoken messages should be surrounded in Quotes.  
Called from GetChatStringWithHyperlinks() and GetChatString().  
See CBUtils::CBStringAddQuotes().  
Parameters:
sString 
    A reference to a string representing the spoken portion of a Chat Message.  Upon function return this string has Quotes added to the front and the back if the nChannelID is of a spoken type Chat Channel.  If not, sString remains unchanged.  
Returns:
CB_SUCCESS
Upon return sString shall be surrounded by Quotes if it is on a spoken type Chat Channel.  
 
int  CBChatMessage::IsChatHyperlinked( )
Comments:
Helper function which returns CB_TRUE if this CBChatMessage instance contains a Hyperlink.   
Returns CB_FALSE if there are no Hyperlinks in the Chat Message.  
Parameters:
None 
    
Returns:
CB_TRUE if the Chat Message has at least one Hyperlink.  
CB_FALSE if there or no Hyperlinks in the Chat Message or there is no Chat Text.  
 
int  CBChatMessage::IsLanguageConvertibleText( )
Comments:
Helper function which returns CB_TRUE if this CBChatMessage contains Text which should be subject to potential Language Conversion.     
Returns CB_FALSE if the LanguageID is CB_LANGUAGE_NONE, or if the ChannelID is a Chat Channel which should not be Language Converted (such as CB_CHANNEL_EMOTE).  
Called by the various GetChatString() type functions.  
Parameters:
None 
    
Returns:
CB_TRUE if the Chat Message contains a LanguageID that is not CB_LANGUAGE_NONE and is on an applicable Chat Channel.  
CB_FALSE if nLanguageID is CB_LANGUAGE_NONE or nChannelID represents a Chat Channel which should not be Language Converted.  
 
 

 

 

 

ChatBlade Copyright © Flex Dolphynn