AuthenticationValues Class Reference

Inheritance diagram for AuthenticationValues:

[legend]

Collaboration diagram for AuthenticationValues:

[legend]

Public Member Functions
	AuthenticationValues (void)
nByte	getType (void) const
AuthenticationValues &	setType (nByte type)
const Common::JString &	getParameters (void) const
AuthenticationValues &	setParameters (const Common::JString &parameters)
AuthenticationValues &	setParametersWithUsernameAndToken (const Common::JString &username, const Common::JString &token)
const Common::JVector< nByte > &	getData (void) const
AuthenticationValues &	setData (const Common::JVector< nByte > &data)
const Common::JString &	getSecret (void) const
const Common::JString &	getUserID (void) const
AuthenticationValues &	setUserID (const Common::JString &userID)
virtual Common::JString &	toString (Common::JString &retStr, bool withTypes=false) const
Public Member Functions inherited from Base
virtual	~Base (void)
Public Member Functions inherited from ToString
virtual	~ToString (void)
virtual JString	typeToString (void) const
JString	toString (bool withTypes=false) const

Additional Inherited Members
Static Public Member Functions inherited from Base
static void	setListener (const BaseListener *baseListener)
static int	getDebugOutputLevel (void)
static bool	setDebugOutputLevel (int debugLevel)
static const LogFormatOptions &	getLogFormatOptions (void)
static void	setLogFormatOptions (const LogFormatOptions &options)

Detailed Description

Container for user authentication in Photon.

Remarks

On Photon, user authentication is optional but can be useful in many cases. If you want to use Client::opFindFriends(), a unique ID per user is very practical.

There are basically three options for user authentication: None at all, the client sets some UserId or you can use some account web-service to authenticate a user (and set the UserId server-side).

Custom Authentication lets you verify end-users by some kind of login or token. It sends those values to Photon which will verify them before granting access or disconnecting the client.

If you don't set a user ID through setUserID() for the AuthenticationValues instance that you pass to Client::connect(), then Photon generates a unique user ID (which fulfills the requirements of a GUID) for you, which can be retrieved through Client::getUserID(), once the Client instance has notified Listener::connectReturn() about having successfully finished the connection procedure. Once you have set a user ID, the Client instance caches it until you either override it or until the end of the lifetime of the Client instance.

To be able to rejoin a room and to be recognized there as the previous user it is critical to continue to use the same user ID.

Therefor you should store the user ID in permanent storage and set it to that same stored value whenever you want to connect as that user, even if you let Photon initially generate that ID. Otherwise Photon would generate a new user ID for you whenever you construct a new Client instance (i.e. when the user restarts your app).

Constructor & Destructor Documentation

AuthenticationValues()

AuthenticationValues

(

void

)

Constructor.

Member Function Documentation

getType()

nByte getType

(

void

)

const

Returns

the type of the "Custom Authentication"service that will be used.

See also

setType()

setType()

AuthenticationValues & setType

(

nByte

type

)

Sets the type of the "Custom Authentication" service that will be used. The initial value before the first call to this function is CustomAuthenticationType::NONE.

Note

Any custom authentication type aside from CustomAuthenticationType::NONE requires you to set up an authentication service of matching type for your appID at https://www.photonengine.com/dashboard

Parameters

type	needs to match one of the values in CustomAuthenticationType

Returns

a reference to the instance on which it was called to allow for chaining multiple setter calls

See also

getType(), CustomAuthenticationType

getParameters()

const JString & getParameters

(

void

)

const

Returns

the HTTP GET parameters that will be forwarded to the authentication service.

See also

setParameters(), setParametersWithUsernameAndToken(), getData(), setData()

setParameters()

AuthenticationValues & setParameters

(

const Common::JString &

parameters

)

Sets the HTTP GET parameters that will be forwarded to the authentication service to the provided parameters.

The provided parameter string must contain any (HTTP GET) parameters that are expected by the used authentication service.

Remarks

Standard HTTP GET parameters are used here and passed on to the authentication service that's defined for the provided authentication type in the Photon Cloud Dashboard.

Parameters

parameters

needs to be a valid HTTP GET string (i.e. param1=value1&param2=value2&param3=value3)

Returns

a reference to the instance on which it was called to allow for chaining multiple setter calls

See also

getParameters(), setParametersWithUsernameAndToken(), getData(), setData()

setParametersWithUsernameAndToken()

AuthenticationValues & setParametersWithUsernameAndToken	(	const Common::JString &	username,
		const Common::JString &	token
	)

Sets the HTTP GET parameters that will be forwarded to the authentication service to the provided username and token.

Calling this function is equivalent to setParameters(Common::JString(L"username=") + username + "&token=" + token).

Parameters

username	the username of the user that should be authenticated
token	the authentication token needed by the authentication service to verify the user

Returns

a reference to the instance on which it was called to allow for chaining multiple setter calls

See also

getParameters(), setParameters(), getData(), setData()

getData()

const JVector< nByte > & getData

(

void

)

const

Returns

the HTTP POST data that will be forwarded to the authentication service.

See also

getParameters(), setParameters(), setParametersWithUsernameAndToken(), setData()

setData()

AuthenticationValues & setData

(

const Common::JVector< nByte > &

data

)

Sets the HTTP POST data, that will be forwarded to the authentication service, to the provided data.

The provided data needs to match what is expected by the used authentication service.

Remarks

The provided data is passed on to the authentication service that's defined for the provided authentication type in the Photon Cloud Dashboard.

Parameters

data	the data to be used in the body of the POST request.

Returns

a reference to the instance on which it was called to allow for chaining multiple setter calls

See also

getParameters(), setParameters(), setParametersWithUsernameAndToken(), getData()

getSecret()

const JString & getSecret

(

void

)

const

After initial authentication, Photon provides a secret for this client / user, which is subsequently used as (cached) validation internally.

Remarks

This is publicly read-accessible only for debugging purposes. For normal operations it is entirely unnecessary for the app code to ever access this value.

Returns

the cached secret

getUserID()

const JString & getUserID

(

void

)

const

Returns

the unique user ID

See also

setUserID()

setUserID()

AuthenticationValues & setUserID

(

const Common::JString &

userID

)

Sets the unique user ID.

Parameters

userID

a string that needs to be unique per user among all users of your app

Returns

a reference to the instance on which it was called to allow for chaining multiple setter calls

See also

getUserID()

toString()

JString & toString ( Common::JString &  retStr, bool  withTypes = false  ) const

virtual

Remarks

The cost of this function depends a lot on implementation details of the implementing subclasses, but for container classes this function can become quite expensive, if the instance contains huge amounts of data, as its cost for many container class implementations increases disproportionately high to the size of the payload.

Parameters

retStr	reference to a string, to store the return-value in; the information, which is generated by this function, will be attached at the end of any eventually existing previous content of the string
withTypes	set to true, to include type information in the generated string

Returns

a JString representation of the instance and its contents for debugging purposes.

Implements ToString.