UserClient Class Reference

#include <UserClient.h>

Inheritance diagram for UserClient:

Collaboration diagram for UserClient:

Public Types
enum	Reason {   kReason_ClientForcedLogout = 0, kReason_ServerForcedLogout, kReason_ChatRoomFull, kReason_ChatRoomUserLeft,   kReason_ChatRoomClosed, kReason_ChatRoomKickedByAdmin, kReason_ChatRoomWrongPassword, kReason_ChatRoomDoesNotExist,   kReason_ChatRoomBanned, kReason_IncorrectLoginDetails, kReason_AccountBlocked }
enum	{ kState_Online = (1<<0), kState_FriendRequest = (1<<1), kState_GameInvite = (1<<2), kState_Message = (1<<3) }
enum	VariableAccess { kPrivateRead = 0, kPrivateReadWrite = 1, kPublicReadPrivateReadWrite = 2, kPublicReadPrivateRead = 3 }
Public Types inherited from MutexClass
enum	{ kNoOwnerThread = -1 }

Public Member Functions
bool	Start (void)
	Because this uses a TransportUDP connection it will call XPURL::RegisterDefaultTransports()
bool	Stop (void)
void	SetServer (const XPAddress &address)
bool	CreateLoginUser (const char *name, const char *password, const char *emailAddress="", const char *optionalID="")
bool	LoginUser (const char *name, const char *password)
bool	ChangePassword (const char *password="")
bool	ChangeEmail (const char *emailAddress="")
int	GetLoginID (void)
	Returns the login ID when the user is logged in or UserInfo::kAnyLoginID when the user is not logged in.
std::string	GetLoginName (void)
	Returns the login name as stored on the server when the user is logged in.
bool	LogoutUser (void)
	Logs out a user.
bool	DeleteUser (void)
	Deletes a user that is currently logged in.
bool	SendMessageTo (const int loginID, const char *message="")
	Sends a message from a logged in user to a login ID.
bool	AddFriend (const int friendLoginID)
	Request to add someone as a friend.
bool	AuthoriseFriendRequest (const int friendLoginID)
	Authorise a friend request from a UserInfo that has the bit kState_FriendRequest set in mState.
bool	DenyFriendRequest (const int friendLoginID)
	Deny a friend request from a UserInfo that has the bit kState_FriendRequest set in mState.
bool	RemoveFriend (const int friendLoginID)
	Remove a user from the friend list. The user info changes will stop tracking.
void	AnswerMessage (const int fromLoginID=UserInfo::kAnyLoginID)
	Call this to clear the state for a received message.
int	GetState (void)
bool	SendGameInvite (const int friendLoginID, const char *invite="")
	Sends a game invite to a friend. Only friends can receive game invites from a user.
bool	CancelGameInvite (const int friendLoginID)
	Cancel a game invite to a friend.
bool	AnswerGameInvite (const int friendLoginID=UserInfo::kAnyLoginID)
	Call this to clear the state for a received game invite from a specific friend or by default all game invites.
bool	SetVariable (const int section, const char *name, const char *value=0, const VariableAccess access=kPrivateReadWrite)
bool	GetVariable (const int section, const char *name, const VariableAccess access=kPrivateReadWrite)
bool	GetVariable (const int loginID, const int section, const char *name, const VariableAccess access=kPublicReadPrivateRead)
bool	AddUserInfo (const int loginID, const bool useCache=true, const bool trackChanges=false)
bool	RemoveUserInfo (const int loginID)
	Stops tracking a loginID for changes that have been requested from using AddUserInfo(). If the user is a friend this will not remove the user from the friend list.
bool	GetUserInfo (const int loginID, UserInfo *result)
bool	CreateChatRoom (const char *password=0)
	Create a new chat room and if successful makes this user join the room as the room admin. The user will be notified of the chatRoomID by CallbackChatRoomCreated()
bool	LeaveChatRoom (void)
	Leave a chat room. If the user created the room and the room has no admins left then the room will be closed. All users in the room will be receive CallbackChatRoomLeft() with a reason of kReason_ChatRoomClosed.
bool	EnterChatRoom (const int chatRoomID, const char *password=0)
int	GetCurrentRoom (void)
	Returns the current chatRoomID.
bool	ChatRoomAdminMessage (const char *text, const unsigned int flags=0)
bool	ChatRoomSay (const char *text, const unsigned int flags=0)
bool	ChatRoomWhisper (const int loginID, const char *text, const unsigned int flags=0)
bool	ChatRoomKickUser (const int loginID, const bool ban=false, const char *reason="")
bool	GlobalKickUser (const int loginID, const bool ban=false, const char *reason="")
bool	GlobalRestoreUser (const int loginID)
	If a user account has been globally banned this will restore the account to active service.
bool	IsRoomAdmin (void)
	If the user is a room admin this will return true.
bool	IsSuperAdmin (void)
	If the user is a super admin this will return true.
bool	PlayingAGame (const bool playing=false, const char *url="")
bool	GetPlayingAGame (void)
	Gets the state set by PlayingAGame()
std::string	GetPlayingAGameURL (void)
	Gets the url state set by PlayingAGame()
std::string	GetLastOnlineTime (void)
	Gets the last time this user account logged in.
bool	RequestUserNonce (const int seconds)
bool	RequestNamesLike (const char *match="", const bool banned=false)
int	GetPendingGetVariableRequests (void)
Public Member Functions inherited from BaseTransportServer
void	SetEncryptionKey (const void *data, const int length)
virtual bool	StartWithTransport (Transport *transport, const bool allowDelete=true, const bool isListen=true)
size_t	GetNumConnections (void) const
	Returns the number of active connections.
size_t	GetNumTotalSessions (void) const
	Returns the total number of connections.
bool	SetAsDisconnecting (Transport *transport)
	This will put the connection into a list pending disconnection after a timeout period.
Public Member Functions inherited from ThreadClass
	ThreadClass ()
virtual	~ThreadClass ()
void	Sleep (int milliseconds)
Public Member Functions inherited from MutexClass
	MutexClass ()
virtual	~MutexClass ()
void	Lock (void)
void	UnLock (void)
Public Member Functions inherited from Thread
	Thread ()
virtual	~Thread ()
void	Begin (ThreadClass *threaded_class)
void	Terminate (void)
bool	GetTerminated (void)
bool	GetEverTerminated (void)
bool	GetIsRunning (void) const
void	SetPreferredProcessor (int processor=kReplicaNetPreferredProcessorOSChoice)
int	GetPreferredProcessor (void)

Protected Member Functions
virtual void	CallbackConnectionEstablished (Transport *transport)
	User extensible callbacks. More...
virtual void	CallbackUserLogin (const int loginID)
	A virtual callback that is triggered when the user successfully logs in.
virtual void	CallbackUserLoginFailed (const Reason reason)
	A virtual callback that is triggered when the user login attempt fails.
virtual void	CallbackUserLogout (const Reason reason)
	A virtual callback that is triggered when the user logs out.
virtual void	CallbackUserAlreadyExists (const int loginID)
	A virtual callback that is triggered when the user account already exists.
virtual void	CallbackUserLoginFromOtherClient (void)
	A virtual callback that is triggered when the user is logged out due to the same account being logged in on another instance.
virtual void	CallbackMessageReceived (const int fromLoginID, const char *message)
virtual void	CallbackFriendDeleted (const int loginID)
	A virtual callback that is triggered when the user deletes a friend.
virtual void	CallbackFriendAdded (const UserInfo &user)
	A virtual callback that is triggered when a friend UserInfo is added. A UserInfo can be added when UserInfo::GetState() has kState_FriendRequest set for a pending friend request.
virtual void	CallbackFriendUpdated (const UserInfo &user)
	A virtual callback that is triggered when a UserInfo is changed.
virtual void	CallbackStateChange (const int previousState, const int newState)
	A virtual callback that is triggered when the state changes for this instance.
virtual void	CallbackGotVariable (const int loginID, const int section, const char *name, const char *value, const VariableAccess access)
	A virtual callback that is triggered when GetVariable() has read a variable from the server.
virtual void	CallbackVariableNotFound (const int loginID, const int section, const char *name, const VariableAccess access)
	A virtual callback that is triggered when GetVariable() has failed to read a variable from the server.
virtual void	CallbackUserInfoDeleted (const int loginID)
	A virtual callback that is triggered when the user deletes a user info request.
virtual void	CallbackUserInfoAdded (const UserInfo &user)
	A virtual callback that is triggered when a AddUserInfo request has succeeded.
virtual void	CallbackUserInfoUpdated (const UserInfo &user)
	A virtual callback that is triggered when a UserInfo is changed.
virtual void	CallbackChatRoomCreated (const int chatRoomID)
virtual void	CallbackChatRoomEntered (const int chatRoomID)
virtual void	CallbackChatRoomEnterFailed (const int chatRoomID, const Reason reason)
virtual void	CallbackChatRoomLeft (const Reason reason)
virtual void	CallbackChatRoomUserEntered (const UserInfo &user)
virtual void	CallbackChatRoomUserLeft (const RNReplicaNet::RNLobby::UserInfo &user, const Reason reason)
virtual void	CallbackChatRoomMessage (const char *text, const UserInfo &user, const bool whispered, const bool isAdminMessage, const unsigned int flags)
virtual void	CallbackChatRoomKicked (const char *reason, bool banned, const UserInfo &user)
virtual void	CallbackGlobalKicked (const char *reason, bool banned, const UserInfo &user)
virtual void	CallbackPasswordChanged (void)
virtual void	CallbackCannotChangePassword (void)
virtual void	CallbackEmailChanged (void)
virtual void	CallbackCannotChangeEmail (void)
virtual void	CallbackGotUserNonce (const char *userNonce, const int seconds)
virtual void	CallbackNewStatsAvailable (const int lastUpdatedTitleID)
	A virtual callback that is triggered when the StatServer updates any variables for this user.
virtual void	CallbackNamesLikeBegin (const char *match, const bool banned)
virtual void	CallbackNamesLike (const UserInfo &user)
	A virtual callback that is triggered when RequestNamesLike is used.
virtual void	CallbackNamesLikeEnd (void)
	A virtual callback that is triggered when RequestNamesLike is used.
void	CallbackTidy (void)
bool	CallbackPoll (void)
bool	CallbackParseValidMessage (Transport *transport, DynamicMessageHelper &message, const size_t length)
Protected Member Functions inherited from BaseTransportServer
virtual bool	PackageAndSendData (Transport *transport, const DynamicMessageHelper &message)
	The class mutex is locked during the context of this function.
virtual bool	CallbackParsePacketData (Transport *transport, void *data, size_t &length, DynamicMessageHelper &result, Entry &entry)
virtual void	CallbackAccepted (Transport *transport)
	Called when the server accepts a connection or when a non-listen class instance connection gets a first valid reply from the server.
virtual void	CallbackDisconnected (Transport *transport)
	Called when the transport is disconnected. This is also called if there is a problem trying to connect. It is therefore possible for a non-listen class instance to receive this callback without a corresponding CallbackAccepted()
virtual void	CallbackDataReceived (DynamicMessageHelper &message)
virtual void	CallbackDataSend (DynamicMessageHelper &message)
virtual void	CallbackQueryReplyTime (const float seconds)
int	ThreadEntry (void)
void	GenerateNewNonce (void)
int	GetConnectionNOnce (Transport *transport=0, const Entry *entry=0)
	Gets the connection's NOnce with respect to a Transport.
int	CalculateConnectionNOnce (Transport *transport)
const Entry *	FindEntry (Transport *transport)
Protected Member Functions inherited from ThreadClass
void	DoQuitNow (const int returnCode)
void	CheckQuit (void)

Additional Inherited Members
Static Public Member Functions inherited from BaseTransportServer
static SysTimeType	FloatTime (void)
Static Public Member Functions inherited from Thread
static int	CallThreadEntry (ThreadClass *thread_class)
static int	GetCurrentProcessorNumber (void)
static size_t	GetNumAllocated (void)
static size_t	GetNumActive (void)
Static Protected Member Functions inherited from ThreadClass
static size_t	GetNumAllocated (void)
Protected Attributes inherited from BaseTransportServer
Transport *	mTransport
bool	mAllowDelete
int	mNOnce
std::map< Transport *, Entry >	mConnected
bool	mIsListen
bool	mClientGotAPacket
bool	mClientIsStable
Entry	mClientEntry
size_t	mNumConnections
size_t	mNumTotalConnections

Detailed Description

Maintains a connection to the UserServer. This allows access to user accounts, friends and user persistent data for each title.

Member Function Documentation

bool AddUserInfo	(	const int	loginID,
		const bool	useCache = true,
		const bool	trackChanges = false
	)

Requests UserInfo from a loginID. CallbackUserInfo() is triggered when a request succeeds and CallbackUserInfoFailed() on failure. This is useful for maintaining a list of recent players the user has encountered.

Parameters

loginID	The loginID to request information for.
useCache	When true if possible use the cached information.
trackChanges	When true this asks the server to send any changes of the loginID to this user. The server will expire old requests when the user logs out to avoid too much server load. RemoveUserInfo() can be used to forget tracking user changes for a loginID.

virtual void CallbackConnectionEstablished ( Transport *  transport )

inlineprotectedvirtual

User extensible callbacks.

A virtual callback that is triggered when the UserClient connects the the UserServer.

virtual void CallbackMessageReceived ( const int  fromLoginID, const char *  message  )

inlineprotectedvirtual

A virtual callback that is triggered when the user receives message from another user.

Parameters

message

The pointer to the message will be freed as soon as this callback returns so do not store the pointer, store the contents of the pointer instead.

virtual void CallbackNamesLikeBegin ( const char *  match, const bool  banned  )

inlineprotectedvirtual

A virtual callback that is triggered when RequestNamesLike is used.

Parameters

match	The corresponding match parameter that was used for RequestNamesLike().
match	The corresponding banned parameter that was used for RequestNamesLike().

bool CallbackParseValidMessage ( Transport *  transport, DynamicMessageHelper &  message, const size_t  length  )

protectedvirtual

Called from the scope of the thread but without the class mutex being locked. If a MessageHelper::Exception() is caught by this server class the connection will be terminated.

Reimplemented from BaseTransportServer.

bool CallbackPoll ( void  )

protectedvirtual

Called from the scope of the thread but without the class mutex being locked. This can be called with or without a valid mTransport

Reimplemented from BaseTransportServer.

void CallbackTidy ( void  )

protectedvirtual

This callback may be used to tidy allocation of objects when the thread terminates. The class mutex is locked when executing this callback.

Reimplemented from BaseTransportServer.

bool ChatRoomAdminMessage	(	const char *	text,
		const unsigned int	flags = 0
	)

Only chat room admins or super admins can use this function.

Parameters

text	The text string is limited to 384 chars. (UserServerPrivate::kMaximumMessageSize)
flags	User defined flags that will be sent to all recipients.

bool ChatRoomKickUser	(	const int	loginID,
		const bool	ban = false,
		const char *	reason = ""
	)

Kicks and optionally bans the user loginID from the currently joined chat room, until the room is destroyed and then created again. Only chat room admins or super admins can use this function.

Parameters

reason

The text string is limited to 384 chars. (UserServerPrivate::kMaximumMessageSize)

bool ChatRoomSay	(	const char *	text,
		const unsigned int	flags = 0
	)

Say some text that is publicly viewable in the current room.

Parameters

text	The text string is limited to 384 chars. (UserServerPrivate::kMaximumMessageSize)
flags	User defined flags that will be sent to all recipients.

bool ChatRoomWhisper	(	const int	loginID,
		const char *	text,
		const unsigned int	flags = 0
	)

Whisper a message to someone in the chat room.

Parameters

text	The text string is limited to 384 chars. (UserServerPrivate::kMaximumMessageSize)
flags	User defined flags that will be sent to all recipients.

bool CreateLoginUser	(	const char *	name,
		const char *	password,
		const char *	emailAddress = "",
		const char *	optionalID = ""
	)

Will try to create an account and then login if it was created. If the account already exists or the optionalID check finds a duplicate ID then CallbackUserAlreadyExists() is called and the user should try to use LoginUser() instead. When creating a login the duplicate name check is not case sensitive so that if someone has the name "Fred" then someone else will not be able to create the name "fred".

Parameters

name	The name to use for the account.
password	The password to use for the account.
emailAddress	The email address to use for the account. The email address can be used to request a password reset using the ASP web lobby interface.
The	optional ID to use for the account. If the optional ID is not an empty string then it is used to detect for more than one account being created by a person or machine. For example the string could be a hash of the user's credit card information, or the MAC address of the machine.

bool EnterChatRoom	(	const int	chatRoomID,
		const char *	password = 0
	)

Attempts to join a room. CallbackChatRoomEntered() will be called if successful and CallbackChatRoomEnterFailed() will be called if not successful. Super admins can enter rooms without needing to know the password.

int GetState

(

void

)

Returns a state for this instance that can be displayed as an icon on the screen.

Returns

A combination of kState_*

bool GetUserInfo	(	const int	loginID,
		UserInfo *	result
	)

Using the currently known list of users and friends this will try to instantly return the most up to date UserInfo.

Parameters

loginID	The loginID to search for.
result	If not null this is a pointer to the resultant UserInfo.

Returns

Returns true if the loginID was found. If false is returned the contents of result is unchanged.

bool GetVariable	(	const int	section,
		const char *	name,
		const VariableAccess	access = kPrivateReadWrite
	)

Invokes CallbackGotVariable() when the variable is retrieved from the server. The name string is limited to 128 chars. (StatServerPrivate::kMaximumPairValueSize)

bool GetVariable	(	const int	loginID,
		const int	section,
		const char *	name,
		const VariableAccess	access = kPublicReadPrivateRead
	)

Invokes CallbackGotVariable() when the variable is retrieved from the server. The name string is limited to 128 chars. (StatServerPrivate::kMaximumPairValueSize)

bool GlobalKickUser	(	const int	loginID,
		const bool	ban = false,
		const char *	reason = ""
	)

Kicks globally across all rooms and optionally bans the user loginID account. Only super admins have the ability for this function to succeed. If the user is banned the user will not be able to login again until the block is lifted in the database.

Parameters

reason

The text string is limited to 384 chars. (UserServerPrivate::kMaximumMessageSize)

bool LoginUser	(	const char *	name,
		const char *	password
	)

Will try to login an existing account. CallbackUserLogin() will be called if the name and password are correct. CallbackUserLoginFailed() will be called if the name or password were incorrect.

Parameters

name	The name of the user. This is not case sensitive. However the original case of the name supplied to CreateLoginUser will be displayed.
password	The password of the user. This is case sensitive.

bool PlayingAGame	(	const bool	playing = false,
		const char *	url = ""
	)

Flags if this user is playing a game. This causes the UserInfo friend icons to update.

Parameters

playing	Use true to indicate the user is playing a game, the optional url will be used. When playing is false the optional url will not be used.
url	An optional url to indicate what game the user is playing. The text string is limited to 384 chars. (UserServerPrivate::kMaximumMessageSize)

bool RequestNamesLike	(	const char *	match = "",
		const bool	banned = false
	)

Requests names that are like the supplied parameter. This causes CallbackNamesLikeBegin,CallbackNamesLike and CallbackNamesLikeEnd to be called once the server replies. By default active accounts are searched. Only super admins are able to search banned accounts.

bool RequestUserNonce

(

const int

seconds

)

Requests a user nonce from the server that can be used to securely identify this user to any other RNLobby supported service. When the user nonce is ready CallbackGotUserNonce() is called. The user nonce will be valid for a number of requested seconds of time. The user nonce can only be used once before it becomes invalid.

void SetServer

(

const XPAddress &

address

)

Sets the address and port of the server. The default for the instance of the class is localhost and port UserServer::kDefaultPort or the address resolved by a successful BackendClient::Start().

Parameters

address

The new address and port number to use for the server

bool SetVariable	(	const int	section,
		const char *	name,
		const char *	value = 0,
		const VariableAccess	access = kPrivateReadWrite
	)

Only allow write access to our own variable space. Setting a null value will erase that value if there is access to do so. The name and value string is limited to 128 chars. (StatServerPrivate::kMaximumPairValueSize)

bool Stop ( void  )

virtual

Stops the thread. If this function is overridden then this base implementation must also be called. This will not generate CallbackDisconnected() events for any existing connections.

Returns

Success returns true, failure returns false.

Reimplemented from BaseTransportServer.