Maintains a connection to the AdvertiseServer. More...

#include <AdvertiseClient.h>

Inheritance diagram for AdvertiseClient:

[legend]

Collaboration diagram for AdvertiseClient:

[legend]

Classes
class	PingServer

struct	ServerInfo

Public Member Functions
bool	Start (void)
	Because this uses a TransportUDP connection it will call XPURL::RegisterDefaultTransports()

bool	StartLAN (void)
	This starts this class to only advertise and find sessions on the LAN.

void	SetServer (const XPAddress &address)

bool	AdvertiseSession (const char url, const char userData="")

bool	RulesChanged (void)
	The user may call this notify the server that the session rules have changed. This then causes a new rules list to be requested by CallbackWantRules.

bool	PlayersChanged (void)
	The user may call this notify the server that the session players list has changed. This then causes a new players list to be requested by CallbackWantPlayers.

bool	StopAdvertiseSession (void)

bool	GetListings (const unsigned int maxResults=10, const unsigned int offset=0, const char *filter=0)

bool	StopListings (void)
	Stop the current request for listings.

bool	RequestRules (const int serverIndex)
	Request the rules for a specific server. CallbackRulesBegin etc will be called when the rules have been fetched.

bool	RequestPlayers (const int serverIndex)
	Request the players for a specific server. CallbackPlayersBegin etc will be called when the players have been fetched.

bool	RequestLatency (const int serverIndex)

bool	GetAnyActivePings (void) const
	Returns true if there are any pings active.

bool	AddRule (const char rule, const char userData="")

bool	AddPlayer (const char name, const char userData="", const int loginID=UserInfo::kAnyLoginID)

bool	SendReliableMessage (const int serverIndex, const void *data, const int length)

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)

virtual bool	Stop (void)

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	CallbackWantRules (void)
	This is called by AdvertiseClient when the user needs to supply rules for the currently advertised server.

virtual void	CallbackWantPlayers (void)
	This is called by AdvertiseClient when the user needs to supply players for the currently advertised server.

virtual void	CallbackGotServerIndex (const int serverIndex)
	This is called when the server index is known for the currently advertised server.

virtual void	CallbackListingsBegin (void)
	This is called at the start when the listings are refreshed.

virtual void	CallbackListingsEntry (const int serverIndex, const int hostLoginID, const char url, const char userData, const float age, const XPAddress &address)

virtual void	CallbackListingsComplete (void)
	This is called when there are no more listings.

virtual void	CallbackRulesBegin (const int serverIndex)
	This is called the start when the rules for a server index are updated.

virtual void	CallbackRule (const int serverIndex, const char rule, const char userData)

virtual void	CallbackRulesComplete (const int serverIndex)

virtual void	CallbackPlayersBegin (const int serverIndex)

virtual void	CallbackPlayer (const int serverIndex, const char name, const char userData, const int loginID)

virtual void	CallbackPlayersComplete (const int serverIndex)

virtual void	CallbackLatencyTo (const int serverIndex, const float latency, const float packetLossPercent)

virtual void	CallbackMessageReceived (const int sourceLoginID, const void *data, const int length)

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)

Protected Attributes
XPAddress	mServerAddress

bool	mIsAdvertising

std::string	mCurrentURL

std::string	mCurrentUserData

bool	mDoingListing

bool	mWantRules

bool	mDoingRules

bool	mWantPlayers

bool	mDoingPlayers

XPSocketUrgent *	mBroadcast

std::string	mBroadcastURL

std::string	mBroadcastData

std::map< int, XPAddress >	mGotReplyFrom

int	mBroadcastServerID

XPAddress	mCurrentReply

int	mCurrentNOnce

SysTimeType	mRequestListingTime

std::list< std::pair < SysTimeType, int > >	mRequestRulesTimes

std::list< std::pair < SysTimeType, int > >	mRequestPlayersTimes

PingServer	mPingServer

bool	mServerAddressSet

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

Additional Inherited Members
Public Types inherited from MutexClass
enum	{ kNoOwnerThread = -1 }

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)

Detailed Description

Maintains a connection to the AdvertiseServer.

Member Function Documentation

bool AddPlayer	(	const char *	name,
		const char *	userData = `""`,
		const int	loginID = `UserInfo::kAnyLoginID`
	)

Adds a player to an advertised server. This must only be called during CallbackWantPlayers()

Parameters

name	The name of the player. This need not always be the name, it could be any user defined data in the form of a text string.
userData	Any user defined data as a text string.
loginID	This loginID may be the same as the loginID from UserClient::GetLoginID(), this is left to the user to implement if required.

bool AddRule	(	const char *	rule,
		const char *	userData = `""`
	)

This must only be called during CallbackWantRules()

Parameters

rule	The rule name as a text string.
userData	The data attached to this rule name;

bool AdvertiseSession	(	const char *	url,
		const char *	userData = `""`
	)

One advertised session for each instance of this class. This can be called with any updated details as often as required. Typically this will be used to advertise the exported URL from a NATUDP transport or a ReplicaNet/XPSession session using NATUDP. If using ReplicaNet or XPSession and the instance is a session master (ReplicaNet::IsMaster() == true) or using a NATUDP transport it is a good idea to regularly export the url and call this function with the details. This is because the url can change as the NAT resolution processes does its work. Please see Example11 for details. This starts the "getinfo" advertise using TransportConfig::SetInfoString(url + userData).

virtual void CallbackConnectionEstablished ( Transport * transport )

inlineprotectedvirtual

User extensible callbacks.

This callback is not triggered during a LAN session query.

virtual void CallbackLatencyTo	(	const int	serverIndex,
		const float	latency,
		const float	packetLossPercent
	)

inlineprotectedvirtual

This is called when the latency to a server index has been calculated.

Parameters

serverIndex	The server index from CallbackListingsEntry().
latency	This is the time taken in seconds for a packet to reach the machine that is advertising the server index. This is half round trip ping time.
packetLossPercent	The packet loss percentage.

virtual void CallbackListingsEntry	(	const int	serverIndex,
		const int	hostLoginID,
		const char *	url,
		const char *	userData,
		const float	age,
		const XPAddress &	address
	)

inlineprotectedvirtual

This is called when there is a listings entry.

Parameters

serverIndex	The server index that can be used to identify this entry with other callbacks or with RequestRules() for example.
hostLoginID	The loginID used to create this advertised entry.
url	The URL passed to AdvertiseSession()
userData	The user data passed to AdvertiseSession()
age	In seconds, how long ago this entry was first advertised.
address	The external address of the machine doing the advertise from the point of view of the AdvertiseServer. If AdvertiseSession() is used on a multihomed machine this external address may not be the same address the advertised game server is bound to as indicated in the URL.

virtual void CallbackMessageReceived	(	const int	sourceLoginID,
		const void *	data,
		const int	length
	)

inlineprotectedvirtual

This is called when a user defined message is received.

Parameters

sourceLoginID	The source loginID of the packet.
data	The message data that was sent.
length	The message data length that was sent.

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.

virtual void CallbackPlayer	(	const int	serverIndex,
		const char *	name,
		const char *	userData,
		const int	loginID
	)

inlineprotectedvirtual

This is called when there is a player for a server index.

Parameters

serverIndex	The server index from CallbackListingsEntry().
name	The name of the player passed to AddPlayer().
userData	The user data of the player passed to AddPlayer().
loginID	The loginID of the player passed to AddPlayer().

virtual void CallbackPlayersBegin ( const int serverIndex )

inlineprotectedvirtual

This is called the start when the players for a server index are updated.

Parameters

serverIndex The server index from CallbackListingsEntry().

virtual void CallbackPlayersComplete ( const int serverIndex )

inlineprotectedvirtual

This is called when there are no more players for a server index.

Parameters

serverIndex The server index from CallbackListingsEntry().

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.

virtual void CallbackRule	(	const int	serverIndex,
		const char *	rule,
		const char *	userData
	)

inlineprotectedvirtual

This is called when there is a rule for a server index.

Parameters

serverIndex	The server index from CallbackListingsEntry().
rule	The rule name passed to AddRule().
userdata	The rule user data passed to AddRule().

virtual void CallbackRulesComplete ( const int serverIndex )

inlineprotectedvirtual

This is called when there are no more rules for a server index.

Parameters

serverIndex The server index from CallbackListingsEntry().

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 GetListings	(	const unsigned int	maxResults = `10`,
		const unsigned int	offset = `0`,
		const char *	filter = `0`
	)

Gets listings with an optional filter. Using a filter query increases the load on the database depending on how many filters are used.

Parameters

maxResults	The maximum number of results returned by this query.
offset	The offset into the information stored by the AdvertiseServer that will be returned by this query.
filter	An optional filter to use that is applied at the server before sending data to the client. The filter consists of logical expressions separated by a new-line or semi-colon. For example: Setting a filter to be "rule.needPass = 1;rule.dedicated = 0;" will only return servers that have the rules called needPass and dedicated which are equal to 1 and 0 respectively. The characters allowed for the rule conditional operand are "=><!"

bool RequestLatency ( const int serverIndex )

Requests the latency to a specific server to be calculated. CallbackLatencyTo will be called when the latency has been calculated.
Depending on how the server is configured and the firewall/NAT used this operation may take a long time to complete or may never complete indicating the server couldn't be reached or there is significant packet loss.

bool SendReliableMessage	(	const int	serverIndex,
		const void *	data,
		const int	length
	)

Sends a reliable message to a server index. The message arrives via CallbackMessageReceived(). Zero length message are not sent. The maximum size of the message that can be sent is 512 bytes.

Returns: false indicates there was an error sending the message, for example the server index may be unknown.

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 AdvertiseServer::kDefaultPort or the address resolved by a successful BackendClient::Start().

Parameters

address The new address and port number to use for the server

bool StopAdvertiseSession ( void )

Stop advertising the session This also stops the "getinfo" advertise using TransportConfig::SetInfoString().

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation