ChatBlade SDK Documentation

Class   CBCommandMap
Header   CBCommandMap.h

Data    Member Summary    Member Details

Information:  

CBCommandMap is a class which stores a pointer to a Slash Command function, and the text Slash Command Aliases that shall invoke that function.  
 
A single Slash Command function may have multiple user entered Slash Commands that all invoke the same function.  
For Example; The OnCommandTell() function may be designed to send a Tell message to another Character.  Players might be able to invoke this function using various Slash Commands  including typing "/tell", "/send", "/t", or "/whisper".  
 
CBCommandMap is the class that relates multiple typed Slash Commands to a single OnCommandXXX() type function.  
 
Each OnCommandXXX() function should have one related instance of a CBCommandMap.  That instance should contain all the typed Slash Commands which invoke that function.  
ChatBlade stores all the OnCommandXXX() Slash Command functions statically in a single class called CBSlashCommands.  
Each function in CBSlashCommands which a Player can invoke should have a related instance of CBCommandMap in order to keep track of which typed Slash Commands can call that function.  
An array of all the CBCommandMap instances is stored statically in CBData::vCommandMapArray.  
ChatBlade shall use this array of CBCommandMap instances to match a Player typed Slash Command with the OnCommandXXX() function that Slash Command should invoke.  
 
Developers should fill up the CBData::vCommandMapArray with CBCommandMap instances in the CBClientImplementation::LoadSlashCommands() function.  See CBClientImplementation and How To Load Slash Commands.  CBSampleImplementation has an example of creating and filling in all the CBCommandMap instances for a Game.  
 
CBData contains a helper Map of all the OnCommandXXX() functions in CBSlashCommands, indexed by the Name of the Function.  This map is statically stored as CBData::mCommandFunctionPointerMap.  
 
The OnCommandXXX() function must take 2 CBSTRING parameters and return an int.  It is Typedefed as:
typedef int ( *ONCOMMANDFUNCTION)(CBSTRING sSlashCommand, CBSTRING sCommandParameters);
 
So to sum up, all OnCommandXXX() functions are stored in CBSlashCommands.  Each function has a CBCommandMap instance that contains a pointer to that function and the text Slash Commands that invoke that function.  An array of these CBCommandMap instances is stored in CBData::vCommandMapArray.  Developers should create the CBCommandMap instances and place them into the array in the CBClientImplementation::LoadSlashCommands() function.  
 
 

Game Developer Implementation:  

Typically Game Developers shall only need to create CBCommandMap instances in the CBClientImplementation::LoadSlashCommands() function, upon Game Startup see How To Load Slash Commands.  
For each OnCommandXXX() function in CBSlashCommands that is used by the Game, Developers should create an instance of CBCommandMap and fill it with the Player typed Slash Commands that shall invoke that function.  After the instance is filled with the function pointer and the typed Slash Commands, that instance should be added to CBData::vCommandMapArray via CBData::AddCommandMap().  
CBSampleImplementation::LoadSlashCommands() has sample code showing how to make all the CBCommandMap instances and fill them with their function pointer and typed Slash Commands.  It also shows adding them to the CBData::vCommandMapArray.  
CBData::mCommandFunctionPointerMap is a helper STL Map of all the CBSlashCommands functions as indexed by their function name (in all UPPERCASE).  
 
 

Source File Comments:  

// Source file for the CBCommandMap class which maps various / Commands to a single function
// For example both /Send and /Tell may map to the OnCommandTell() function
 
// The CBCommandMap class provides the functionality of allowing multiple user entered commands to map to the same function
// This allows for customization of the Slash Command user interface
 
// When the user enters in a Slash Command ChatBlade shall cycle through all the CBCommandMaps
// It shall look for a match for the / Command entered
// If a match is found it shall call the pOnCommandFunction in that CBCommandMap to Invoke the associated OnCommand() Function

Data:  

CBSTRING m_sDescription
        An optional string describing the OnCommandXXX() function contained in this CBCommandMap instance.    
CBSTRING m_sHelpString
        An optional string showing usage information about the OnCommandXXX() function contained in this instance.    
std::vector <CBSTRING> m_vAliasArray
        A vector of all the Slash Command Aliases for this Function.  
ONCOMMANDFUNCTION pOnCommandFunction
        Pointer to the OnCommandXXX() function that the Command Aliases in this CommandMap map to.  
 

Member Function Summary:  

          CBCommandMap()
        Constructor.  
int       Clear()
        Sets pOnCommandFunction to NULL, and erases all Aliases.  
int       SetPointer(ONCOMMANDFUNCTION pOnCommandFunctionPointer)
        Set the function pointer of the OnCommandXXX() function for this Command Map.  
int       AddAlias(CBSTRING sAlias)
        Add in an Alias that shall invoke this Slash Command function.  
int       IsCommand(CBSTRING sCommand)
        Returns CB_TRUE if sCommand is an Alias stored in this CBCommandMap instance.  
int       CallCommand(CBSTRING sCommand, CBSTRING sParameters)
        Invokes the associated Command of this CommandMap instance.  
int       SetDescription(CBSTRING sDescription)
        Sets the Description of the OnCommandXXX() function stored in this CBCommandMap instance.    
CBSTRING  GetDescription()
        Gets the Description of the Slash Command Function stored in this instance.    
int       SetHelpString(CBSTRING sHelpString)
        Sets the Help String of the OnCommandXXX() function stored in this CBCommandMap instance.  .  
CBSTRING  GetHelpString()
        Gets the Help String of the Slash Command Function stored in this instance.  
 

Member Function Detail:  

     CBCommandMap::CBCommandMap()
Comments:
Constructor which sets pOnCommandFunction = NULL.  
Parameters:
None
Returns:
None
 
int  CBCommandMap::Clear()
Comments:
Clears out all data in this Command Map instance.  
Sets pOnCommandFunction to NULL, and erases all Aliases.  Note:  ChatBlade uses the term Alias to mean 2 different things; text Slash Commands which relate to the same OnCommandXXX() function, and Player created Slash Command Macro-like equivalents created by the /alias Command.    
Parameters:
None
Returns:
CB_SUCCESS
 
int  CBCommandMap::SetPointer( ONCOMMANDFUNCTION pOnCommandFunctionPointer)
Comments:
This function sets the OnCommandXXX() function pointer that should be stored in this CBCommandMap instance.  
Should only be called once in a single instance (unless that instance is reused in code).  Each CBCommandMap instance can only store a single ONCOMMANDFUNCTION pointer.  
The function pointer stored with SetPointer() shall be invoked whenever a Player types in a Slash Command Alias stored in the CBCommandMap.  
ChatBlade is designed to have all the OnCommandXXX() functions located statically in a single class called CBSlashCommands.  pOnCommandFunctionPointer should be a pointer to one of that Classes functions.  
To find an OnCommandXXX() function pointer by its text name, ChatBlade has a helper map stored statically in CBData::mCommandFunctionPointerMap that maps each CBSlashCommands function, indexed via the UPPERCASE name of that function.  
The Pointer Map can be used to set the Pointer like so:  SetPointer(CBData::mCommandFunctionPointerMap[_T("ONCOMMANDTELL")]);
Typically called from CBClientImplementation::LoadSlashCommands().  
Parameters:
pOnCommandFunctionPointer
    A pointer to a function that takes 2 CBSTRING parameters and returns an int.  Typically an OnCommandXXX() member function of the CBSlashCommands class.  
Returns:
CB_ERROR_NULL_POINTER if pOnCommandFunctionPointer is NULL.  
CB_SUCCESS if the pointer was Set successfully.  
 
int  CBCommandMap::AddAlias( CBSTRING sAlias)
Comments:
This function adds a typed Slash Command to the list of Slash Commands that shall invoke the function pointed to by this Command Map instance.  
Call this function multiple times to add in various Slash Command Aliases that all map to the same function.  
Each alias should start with a '/' character and be 1 word in length, no spaces.  
Care should be taken that the same Slash Command Alias is not added to multiple CBCommandMap instances.  If the same Slash Command is in more than 1 instance, ChatBlade shall invoke the function mapping to the first one it comes to.  In otherwords, make sure that "/r" is not mapped to both OnCommandReply() and OnCommandRaidChat().  
Slash Command Aliases are case insensitive by being converted to all UPPERCASE before storage.  
Multiple Slash Command Aliases can all invoke the same function.  In such a case call AddAlias() once for each alias.  
For Example:  
    /g, /group, /p, /party, /team, and /fellowship may all invoke the OnCommandGroupChat() function.  
    Each one would be added individually by calling AddAlias() once each to the CBCommandMap instance that contains the OnCommandGroupChat() function pointer.  
The text of the Alias that actually invoked the OnCommandXXX() function gets passed to the function as its first parameter.  But generally this parameter can be ignored.  Most functions won't need to know if they were invoked by /g or /group.  
Typically called from CBClientImplementation::LoadSlashCommands().  
Parameters:
sAlias
    A single word Slash Command the Player would type to invoke the function Mapped in this CBCommandMap instance.  Should start with a '/'.  
Returns:
CB_ERROR_EMPTY_STRING if sAlias is too small to be a real Slash Command.  
CB_SUCCESS if the Alias was added in.  
 
int  CBCommandMap::IsCommand( CBSTRING sCommand)
Comments:
This function checks whether the parameter is an Alias that is stored in this CBCommandMap instance.  
Returns CB_TRUE if sCommand is stored in this instance and CB_FALSE if it is not.  
sCommand is not Case Sensitive.  Case is ignored.  
When a Player types a Slash Command, ChatBlade shall go through all the CBCommandMap instances until IsCommand() returns CB_TRUE for that Slash Command.  It shall then invoke the OnCommandXXX() function stored in the CBCommandMap instance which returned CB_TRUE.  
Called by CBChatHandler::ProcessSlashCommand().  
Parameters:
sCommand
    A Player typed (or ChatBlade added) Slash Command which should be tested to see if it is an Alias stored in this CBCommandMap instance.  
Returns:
CB_FALSE if sCommand is not a Slash Command Alias in this CBCommandMap instance.  
CB_TRUE if sCommand is an Alias stored in this instance.  
 
int  CBCommandMap::CallCommand( CBSTRING sCommand,
CBSTRING sParameters)
Comments:
This function invokes the ONCOMMANDFUNCTION function contained in this CBCommandMap instance (pOnCommandFunction).  
It passes the 2 parameters to the invoked function and returns the return value from the called function.  
sCommand is the Slash Command Typed by the Player.  
sParameters contains any parameters after the Slash Command.  
Called by CBChatHandler::ProcessSlashCommand().  
Parameters:
sCommand
    The Slash Command typed by the Player or added automatically by ChatBlade by default.  
sParameters
    Any additional text typed after the Slash Command, such as the Chat a player wants to send in a group message.  
Returns:
CB_ERROR_NULL_FUNCTION_POINTER if this CBCommandMap instance has a NULL function pointer stored.  
Otherwise returns the return value of the invoked pOnCommandFunction function pointer.  
 
int  CBCommandMap::SetDescription( CBSTRING sDescription)
Comments:
Sets an optional description of the Slash Command Function that is stored in this instance.  
Used by the /chathelp command to provide information to the Player about Slash Command functionality.  
Parameters:
sDescription
    An optional string describing the Slash Command Function that is contained in this CBCommandMap instance.  
Returns:
CB_SUCCESS
 
CBSTRING  CBCommandMap::GetDescription()
Comments:
Returns the description of the OnCommandXXX() function stored in this CBCommandMap instance.  
For Example:  "Command Invoked when a user wants to Send a message to the Auction Channel"
Parameters:
None
Returns:
The text of m_sDescription.  
 
int  CBCommandMap::SetHelpString( CBSTRING sHelpString)
Comments:
Sets an optional usage string describing how to format the commands that invoke the OnCommandXXX() function contained in this instance.  
For Example, sHelpString might contain the string "/AFK Text to display to Players sending you a tell while you are AFK".  
Parameters:
sHelpString
    A string describing the usage (format) of a command to invoke the Slash Command Function stored in this CBCommandMap.  
Returns:
CB_SUCCESS
 
CBSTRING  CBCommandMap::GetHelpString()
Comments:
Returns the optional usage text corresponding to how to use a Slash Command(s) that would invoke the OnCommandXXX() function stored in this instance.   
Used by the /help command to display to the Player how to use a specified Slash Command.  Shows the Command formatting.  
Parameters:
None
Returns:
The text contained in m_sHelpString.  
 
 

 

 

 

ChatBlade Copyright © Flex Dolphynn