Chat SDK
From GameSpy SDK
Chat SDK
Overview
The GameSpy Chat SDK is a portable ANSI-C API used to write chat clients. The current implementation works with IRC servers, however it could be re-implemented to work on another chat network without having to change any user code. The Chat SDK provides an easy way to allow your game's players to chat online. There are no libraries or DLLs to deal with; just add the source files to your project and you're ready to go.
The Chat SDK only deals with data. You will be responsible for creating all the GUI elements that are required for chatting within your game.
Chat Nicknames have a few restrictions based on IRC standards and server requirements. The character limit for chat nicks is 20 characters. The following are the character restrictions:
- The first character cannot be any of the following: +, @, #, :
- Numeric characters are only allowed after the first character.
- All characters in the ASCII character range 34-126 are valid except for character 92.
File Manifest
The following files should be included with this package. If any of the files are missing, please contact devsupport@gamespy.com.
- File
- Description
- chat.h
- GameSpy Chat header (all user functions are prototyped here)
- chatMain.c
- Entry point for all user Chat functions
- chatMain.h
- Common header for internal code
- chatSocket.c
- Implementation of a network-level connection to a chat server
- chatSocket.h
- Header for chat socket functions
- chatHandlers.c
- Code for handling IRC messages
- chatHandlers.h
- Header for callback handling functions
- chatCallbacks.c
- Code for queueing and calling callbacks
- chatCallbacks.h
- Header for callback handling function
- chatChannel.c
- Code for dealing with chat channels and the users in the channels
- chatChannel.h
- Header for accessing and manipulating the channel and user data
- nonport.c
- Platform-specific code
- nonport.h
- Platform-specific header
- hashtable.c
- Hastable implementation
- hashtable.h
- Hashtable headers
- darray.c
- Dynamic-Array implementation
- darray.h
- Dynamic-Array headers
Implementation
Connecting
The first thing to do with Chat is to connect to a server. This is done with either chatConnect, chatConnectSpecial, or chatConnectSecure. Most application will use chatConnect. chatConnectSpecial is used to fill in the user field after the local machine's IP address is known, and chatConnectSecure is used to encrypt the connection.
CHAT chatConnect(const char * serverAddress, int port, const char * nick, const char * user, const char * name, chatGlobalCallbacks * callbacks, chatNickErrorCallback nickErrorCallback, chatConnectCallback connectCallback, void * param, CHATBool blocking)
CHAT chatConnectSpecial(const char * serverAddress, int port, const char * nick, const char * name, chatGlobalCallbacks * callbacks, chatNickErrorCallback nickErrorCallback, chatFillInUserCallback fillInUserCallback, chatConnectCallback connectCallback, void * param, CHATBool blocking)
CHAT chatConnectSecure(const char * serverAddress, int port, const char * nick, const char * name, const char * gamename, const char * secretKey, chatGlobalCallbacks * callbacks, chatNickErrorCallback nickErrorCallback, chatFillInUserCallback fillInUserCallback, chatConnectCallback connectCallback, void * param, CHATBool blocking)
- serverAddress
- the IP address and port of the chat server to which to connect
- port
- the port of the chat server to which to connect
- nick
- the connecting user's nickname
- user
- the user's username. This is only used with chatConnect.
- name
- the user's real name or any other optional info
- gamename, secret key
- used with chatConnectSecure, which is used to encrypt all traffic with the chat server.
- The gamename and secretKey are application-specific - if you are unsure what your gamename and secretKey are, contact devsupport@gamespy.com.
- callbacks
- a pointer to a structure which contains a list of global callbacks to be associated with this connection. The structure also contains a "param" member which is of type pointer to void (void *). This param is passed in as the last argument to all global callbacks.
chatConnect returns a CHAT object. This represents the connection to the chat server. If the return value is NULL, then there was an error establishing the connection.
Connecting should look something like this:
int CMyGame::OnConnect(...)
{
m_chat = chatConnect("irc.mygame.com", 6667, "nick", "user", "email@email.com", &callbacks, callback, this, CHATFalse);
if(m_chat == NULL)
Error();
}
Disconnecting
When the chat connection is ready to be disconnected, just call the chatDisconnect function:
void chatDisconnect(CHAT chat)
This will terminate the connection to the chat server. The chat object cannot be used again. To establish a new connection, chatConnect must be called again. chatDisconnect should always be called to cleanup a connection - the only exception is when chatConnect returns NULL.
Processing
A chat connection must be periodically processed. This is done by calling chatThink:
void chatThink(CHAT chat)
When a connection is processed, it sends any queued outgoing data, reads incoming data, and calls any callbacks generated by the incoming data. This function can be called in an applications main or idle loop. It should be called at least once a second, but it is not necessary to call it more than several times a second (although calling it more often will do no harm).
Entering A Channel
To join a channel, call chatEnterChannel. This function will enter an existing channel if it exists or create a new channel and enter it if it does not exist.
void chatEnterChannel(CHAT chat, const char * channel, const char * password, chatChannelCallbacks * callbacks, chatEnterChannelCallback callback, void * param, CHATBool blocking)
- chat
- the same CHAT object returned by the call to chatConnect
- channel
- the channel that we are trying to enter
- password
- the password required to enter the channel. If no password is required, this can either be NULL or an empty string.
- blocking
- determines if this function should block until the enter attemp has been completed or if it should be returned immediately. In either case, "callback" will be called when the attemp is completed.
Leaving A Channel
To leave a channel, just call chatLeaveChannel:
void chatLeaveChannel(CHAT chat, const char * channel)
This will take you out of the given channel.
UNICODE Support
The GameSpy SDKs support an optional UNICODE interface for widestring applications. To use this interface, first define the symbol "GSI_UNICODE". Then, use widestrings wherever ANSI strings were previously called for. When in doubt, please refer to the header files for specific function declarations.
Although the GameSpy SDK interfaces support UNICODE parameters, some items may be stripped of their extra UNICODE information. These items include: nickname, email address, and URL strings. You may pass in widestring values, but they will first be converted to their ANSI counterparts before transmission.