ChatBlade SDK Documentation

Class   CBChatSampleNetworkClient
Header   CBChatSampleNetworkClient.h

Data    Member Summary    Member Details

Information:  

This Class implements Sample Networking for an imaginary game client, or a Chat Testing application.  
It is not designed for production use, and is a Sample only.  It is not part of the core ChatBlade Classes.  
 
This sample is for use on Windows and makes use of Winsock and Windows Threading.  
This Class makes use of 2 sockets, one to receive and one to transmit.  The receiving socket is implemented in its own Thread.  When a message is received it is placed on the main Windows message queue to get the data to the main application.  
UDP is the protocol used to communicate in a connectionless state.  
 
It is expected that each Game company shall implement varying network backends.  As such this code is expected to be replaced with whatever Networking code is used in the game.  

Game Developer Implementation:  

This Class is just a sample of potential Chat Networking.  It should be replaced by whatever Networking the Game is really using.  
This Class is instantiated as a member of CBSampleImplementation and is primarily used from that class.  
It is designed to work with the Sample Chat Server and Chat Sample Test Client application (CBMFCTestClient).  
When a Chat Message is received over the wire, this class allocates space for that message and throws it into the Games main Windows Message queue.  Upon processing that message the Game should free up the space that was allocated for that message.  See the Chat Sample Test Client (CBMFCTestClient) code for an example of how the message handling might work.  
It is recommended that all packets be encrypted and that Players remain ignorant of each others actual IP address.  All communication should be through Game servers for security.  
Network port values may appear to be Byte Swapped.  As such it is recommended that they be displayed in Hexadecimal for ease of debugging.  For example:  a UDP port specified in code as 0x1984 may end up on the wire on port 0x8419 instead.  
The Encryption keys used to Encode the network packets need to be identical in both the Client and the Server.  If the keys are changed they shall need to be changed in both places.  

Source File Comments:  

// Represents an implementation of Sample network client code for Sample use with ChatBlade
// It is envisioned that each Licensee of ChatBlade shall utilize varying network backends
// As such this network code is intended for sample use and it is expected that game companies shall incorporate another network backend system
 
// This sample utilizes UDP as its networking Protocol and operates in a connectionless state
// Each packet received should be authenticated against a known list of Chat Server addresses
// This sample uses IPv4
 
// Chat messages are sent to a Chat Server which then looks up the addresses of those who should receive the message
// The chat message is then replicated out to those players
// A Sample Chat Server is included as CBSampleChatServer.java
 
// Data sent on the wire is easily Sniffed - for security all packets should be Encrypted before being sent over the net
// For security Players should not be aware of the IP Address of others. Communication should be Client/Server and not Peer to Peer
 
// CBChatSampleNetworkClient makes use of 2 Sockets; one to Receive and one to Transmit
// The receiving Socket is implemented in its own Thread. Chat messages received are sent back to the main application via the Windows Message Queue

Data:  

WSADATA m_wsaData
        Windows Socket data structure.  
SOCKET m_SendingSocket
        Socket that we use to send messages to the Chat Server.  
static SOCKET m_ReceivingSocket
        Socket we receive messages from the Chat Server on.  
static std::set<CBSTRING> m_ChatServerAddressSet
        A list of all the IP Addresses of our potential Chat Servers.  Used to verify incoming Messages.  
CBSTRING m_CurrentChatServerAddress
        The IP Address of the current Chat Server to send to.  
int m_SendingPort
        Our sending UDP Port.  
static int m_nReceivingPort
        Our receiving UDP Port.  
static int m_bKeepListeningFlag
        Flag to tell when to end listening for Chat Messages.  
unsigned m_ReceiveThreadID
        Holds the ThreadID set in _beginthread.  
 

Member Function Summary:  

             CBChatSampleNetworkClient()
        Constructor.  
int          InitializeNetwork()
        Initialize Winsock, set our initial values, and start up our receiving thread.  
int          DeInitializeNetwork()
        Shut down the network.  
unsigned  ThreadedReceiveFunction(void * pArguments)
static __stdcall          Function started in its own Thread to continuously receive Chat Messages from the network.  
static int   IsValidChatServer(CBSTRING sAddress)
        Checks if the address is that of a valid known Chat Server.  
int          SendChatMessage(CBChatMessage cbChatMessage)
        Called by ChatBlade when a Chat Message should be sent to the remote Chat Server for dispersal.  
int          ConvertChatMessageToNetworkString(CBChatMessage cbChatMessage /*IN*/, CBSTRING & sNetworkString /*OUT*/)
        Converts an CBChatMessage instance into its character string representation to enable the text to be sent over the Net.  
static int     ConvertNetworkStringToChatMessage(CBChatMessage & cbChatMessage /*OUT*/, CBSTRING sNetworkString /*IN*/)
        Converts a decoded network received string to an CBChatMessage instance.  
int          WireEncryptString(CBSTRING & sString /*IN OUT*/)
        Encodes a string prior to sending it over the Net.  
static int   WireDecryptString(CBSTRING & sString /*IN OUT*/)
        Decodes a string received over the network.  
int          AddValidChatServerAddress(CBSTRING sAddress)
        Adds in an IPAddress of a valid Chat Server.  
int          SetSendPort(int nPort)
        Sets the UDP Port number used when Transmitting to the Chat Server.  
int          SetReceivePort(int nPort)
        Sets the UDP Port number to Listen on to receive messages.  
int          SetCurrentChatServerAddress(CBSTRING sIPAddress)
        Sets the IP Address of the default Chat Server for this client to send messages to.  
 

Member Function Detail:  

     CBChatSampleNetworkClient::CBChatSampleNetworkClient()
Comments:
Empty Constructor.  
Parameters:
None
Returns:
None
 
int  CBChatSampleNetworkClient::InitializeNetwork()
Comments:
Initializes various Networking components.  
Sets up our Sockets.  Initializes Winsock.  Sets our ports and Chat Server Address.  Starts up our receiving Thread.  
Should be called before doing any actions involving the Network.  
Called from CBSampleImplementation::InitializeChatNetworking().  
Parameters:
None
Returns:
CB_SUCCESS
 
int  CBChatSampleNetworkClient::DeInitializeNetwork()
Comments:
Closes our Sockets and Cleans up WinSock.  Sets m_bKeepListeningFlag to FALSE.  
Should be called once the Client is shutting down.  
Parameters:
None
Returns:
CB_SUCCESS
 
static unsigned __stdcall  CBChatSampleNetworkClient::ThreadedReceiveFunction( void * pArguments)
Comments:
Function implemented in its own Thread in order to receive Chat Network packets.  
This function listens for packets on the UDP port specified by m_ReceivingSocket.  Packets must come from a valid Chat Server IP address.  
When a packet is received this function allocates space for the data and decrypts it.  
It then passes the data to the main application via a PostMessage() Win32 call with the ID of WM_USER_CB_MESSAGE along with a pointer to the allocated Chat Message.  This places the information on the Windows Message Queue.  
It is up to the main Application to process this Windows message and retrieve the data from the allocated pointer and pass that information onto ChatBlade (via CBChatHandler::OnIncomingChatMessage()).  
It is important to free the memory for the Pointer.  Memory is allocated here in ThreadedReceiveFunction() but should be freed in the main Application after the Windows Message has been processed.  
See OnChatMessageReceived() in the ChatBlade Sample Test Client application (CBMFCTestClient).  
Parameters:
pArguments
    Pointer to Void.  Not used.  Just needed to match the Threading requirements.  
Returns:
CB_SUCCESS
 
static int  CBChatSampleNetworkClient::IsValidChatServer( CBSTRING sAddress)
Comments:
This function verifies whether or not the IP address given is that of a Valid Chat Server.  
Used to authenticate received messages and insure that they are not spoofed.  
If sAddress is an address previously passed to AddValidChatServerAddress() this function returns CB_TRUE.  
Called by ThreadedReceiveFunction() once for each packet received.       
Parameters:
sAddress
    The IP Address of a Network packet we want to Authenticate against.  
Returns:
CB_TRUE if sAddress is a valid Chat Server address.  
CB_FALSE if sAddress is not on the list of valid Chat Servers.  
 
int  CBChatSampleNetworkClient::SendChatMessage( CBChatMessage cbChatMessage)
Comments:
Sends a Chat Message to the Chat Server via UDP over the Internet.  
This function performs the actual network transmittal of a Chat Message.  
First the CBChatMessage parameter is converted to a String representation.  Then it is potentially encrypted.  
Finally it is sent via the UDP port specified by m_SendingPort to the Chat Server indicated by m_CurrentChatServerAddress.  
The size of the packet is limited to CB_MAX_UDP_PACKET_SIZE.  
Called by CBSampleImplementation::SendChatMessage().  CBChatHandler::SendChatMessage() is the function that should be invoked to start sending a Chat Message to the Chat Server.  
It is up to the Chat Server to examine each message and forward the Chat Message onto other Players based on the Chat Channel and Destination contained in the message.  
Parameters:
cbChatMessage
    A CBChatMessage instance of a Chat Message we want to send out.  
Returns:
CB_ERROR_UNICODE_CONVERSION if there is an error converting strings when compiling under UNICODE.  
CB_SUCCESS
 
int  CBChatSampleNetworkClient::ConvertChatMessageToNetworkString( CBChatMessage cbChatMessage /*IN*/,
CBSTRING & sNetworkString /*OUT*/)
Comments:
Converts a CBChatMessage instance into a String representation of that instance to facilitate Network transmittal.  
Makes a string out of the CBChatMessage.  
A sample string looks like so:  
    S=VANADIAD=IRRIDIAC=52M=0L=0F=0T=How much for the Sword?
Called by SendChatMessage().  
Parameters:
cbChatMessage 
    A CBChatMessage we want to convert into a string.  
sNetworkString 
    A reference to a CBSTRING that shall hold our string representation of the Chat Message upon function return.  
Returns:
CB_SUCCESS
Upon return sNetworkString shall be filled with a string representing the Chat Message.  
 
static int  CBChatSampleNetworkClient::ConvertNetworkStringToChatMessage( CBChatMessage & cbChatMessage /*OUT*/,
CBSTRING sNetworkString /*IN*/)
Comments:
Converts a string received from a Chat Server into a CBChatMessage instance.  
Text is used to send packets over the Network.  This function converts from text into the CBChatMessage class used by ChatBlade.  
A sample string initially looks like so:
    S=VANADIAD=IRRIDIAC=52M=0L=0F=0T=How much for the Sword?
This function parses that string and fills in the data fields of cbChatMessage.  
The string should already have any Network Encryption removed.  
Called by OnChatMessageReceived() in the ChatBlade Sample Test Client application (CBMFCTestClient).  
Parameters:
cbChatMessage 
    A reference to a CBChatMessage instance which shall hold the data from the Network string upon function return.  
sNetworkString 
    A decrypted string received from the Chat Server representing a Chat Message.  
Returns:
CB_ERROR_INCOMPLETE_MESSAGE if the Chat Message is malformed.  
CB_SUCCESS if the conversion was successful.  
Upon successful return, cbChatMessage is filled with data parsed from sNetworkString.  
 
int  CBChatSampleNetworkClient::WireEncryptString( CBSTRING & sString /*IN OUT*/)
Comments:
Encrypts a string prior to Network transmittal.  
All data passing over the Internet should be encrypted to enhance the security of an application.  Raw text makes things much simpler for any hacking attempts.  
This function encrypts a Chat Message a random amount of times using encryption Keys.  
The encryption found here must match the decryption in the Chat Server.  
For development purposes the Random value can be hard coded to 0 to disable any encryption so that the packets may be monitored.  
The encryption provided by this function is weak.  It is designed to prevent raw text from being sent over the Net.  
Called by SendChatMessage().  
Parameters:
sString 
    A reference to a string which shall be encrypted upon return of the function.  
Returns:
CB_SUCCESS
 
static int  CBChatSampleNetworkClient::WireDecryptString( CBSTRING & sString /*IN OUT*/)
Comments:
Decrypts a Network string and changes it into its original text.  
All data passing over the Internet should be encrypted to enhance the security of an application.  Raw text makes things much simpler for any hacking attempts.  
This function Decrypts a string that had previously been encrypted by WireEncryptString() or the Sample Chat Server.  
Called by ThreadedReceiveFunction().  
Parameters:
sString 
    A reference to an Encrypted string.  Upon function return the string should be Decrypted.  
Returns:
CB_ERROR_BAD_PARAMETER if the string is too small.  
CB_SUCCESS
 
int  CBChatSampleNetworkClient::AddValidChatServerAddress( CBSTRING sAddress)
Comments:
Adds in an IPAddress of a valid Chat Server.  
Only Chat Messages received from valid Chat Servers are processed by the ChatBlade Sample Network code.  
Call this function with the IPAddress (IPv4)for each possible Chat Server.  
For Example: AddValidChatServerAddress(_T("184.47.22.1"));
Parameters:
sAddress
    The IPAddress of an official Chat Server.  
Returns:
CB_SUCCESS
 
int  CBChatSampleNetworkClient::SetSendPort( int nPort)
Comments:
Sets the UDP Port number used when transmitting to the Chat Server.  
The actual port number used may be Byte Swapped.  For Example:  Setting this to port 0x1984 may actually transmit on port 0X8419.  
The Chat Server must be listening on this Port Number in order to receive packets from the Clients.  
Parameters:
nPort
    The UDP Port number used to send our Packets to the Chat Server.  
Returns:
CB_SUCCESS
 
int  CBChatSampleNetworkClient::SetReceivePort( int nPort)
Comments:
Sets the UDP Port number to listen to in order to receive messages from the Chat Server.  
The actual port number used may be Byte Swapped.  For Example:  Setting this to port 0x1985 may actually receive on port 0X8519.  
Two ports are used in the ChatBlade Network Sample, one to receive and one to transmit.  This allows Developers to use one machine to test on.  In production Networking it may be advisable to use a Single port.  
Parameters:
nPort
    The UDP Port number to listen to in order to receive Chat Messages from the Chat Server.  
Returns:
CB_SUCCESS
 
int  CBChatSampleNetworkClient::SetCurrentChatServerAddress( CBSTRING sIPAddress)
Comments:
Sets the IP Address of the default Chat Server for this Client to send messages to.  
All Chat Messages using this Sample Networking shall be sent to this Chat Server IP Address for Chat Message propagation.  
Parameters:
sIPAddress
    The IPAddress of a Chat Server this client should use.  
Returns:
CB_SUCCESS
 
 

 

 

 

ChatBlade Copyright © Flex Dolphynn