TT Client Library 1.0.0
C++ library for Tandem Tales clients.
Loading...
Searching...
No Matches
tt::Client Class Referenceabstract

A client connects to a server to find a partner and play a role in a storytelling session. More...

#include <tt/Client.h>

Collaboration diagram for tt::Client:

Public Member Functions

 Client (const std::string &name, const std::string &password, const std::string &world, Role role, const std::string &partner, const char *key, const std::string &url, int port)
 Constructs a client with the given session preferences, password, API key, and network details.
 Client (const std::string &name, const std::string &world, Role role, const std::string &partner, const std::string &url, int port)
 Constructs a client with the given session preferences and network details, reading the password and API key from the environment.
 Client (const std::string &name, const std::string &world, Role role, const std::string &partner)
 Constructs a client with the given session preferences, reading the password and API key from the environment, and using the default network settings.
 Client (const std::string &name, const std::string &world, Role role)
 Constructs a client with a name, role, and world name, which has no preference for a partner, reading the password and API key from the environment, and using the default network settings.
 Client (const std::string &name)
 Constructs a client with a given name, which has no preference for its role, world, or partner, reading the password and API key from the environment, and using the default network settings.
virtual std::string toString () const
 Gives a string representation of this client.
const std::string & getName () const
 Returns the client's name.
const std::string & getWorldName () const
 Returns the name of the story world this client will play in or is currently playing in.
Role getRole () const
 Returns the role this client wants to play or is currently playing in its session.
const std::string & getPartner () const
 Returns the name of the partner this client wants to play with.
const World * getWorld ()
 Returns a const pointer to the story world in which this client's session is taking place.
std::vector< const Turn * > getHistory () const
 Returns the list of all turns that have been taken so far in this client's session that this client has observed.
const State * getState () const
 Returns the current state of the story world.
std::vector< const Turn * > getChoices () const
 If it is currently this client's turn to act, this method returns the list of turns they can take next.
const std::string & getSession ()
 Returns the ID of this client's session.
std::string execute ()
SSL * connect (const std::string &url, int port)
 Establishes a secure socket to the server based on this client's network configuration.
void sendMessage (const tt::Message &m)
 This method sends a message to the server.
void close ()

Public Attributes

ExternalAPI external
 Used to access external APIs.

Static Public Attributes

static const std::string ENVIRONMENT_VARIABLE_PASSWORD = "password"
 The name of the environment variable where the client expects to find the password this agent will use, unless the password is explicitly set by the agent's constructor.
static const std::string ENVIRONMENT_VARIABLE_API_KEY = "apikey"
 The name of the environment variable where the client expects to find the API key used to authenticate with the service that provides functions which require special external resources or computation.
static const std::string DEFAULT_URL = "localhost"
 The default URL the client will attempt to connect to if one is not explicitly provided in the constructor.
static const int DEFAULT_PORT = 9005
 The default network port the client will attempt to connect to if one is not explicitly provided in the constructor.

Protected Member Functions

void setName (const std::string &name)
 Sets the name this client will use.
void setPassword (const std::string &password)
 Sets the password this client will use.
void setWorldName (const std::string &world)
 Sets the name of the story world this client wants to play in.
void setRole (Role role)
 Sets the role this client wants to play in its session.
void setPartner (const std::string &partner)
 Sets the name of the partner this client wants to play in its session.
virtual void onConnect (const Connect *connect)
 This method is called after the client connects to the server and the server sends the list of available worlds and agents.
virtual void onStart (const World *world, Role role, const State *initial)
 This method is called once when the client's session starts.
virtual void onUpdate (const Status *status)
 This method is called each time the story world changes as a result of a turn the client observes.
virtual int onChoice (const Status *status)=0
 This method is called each time it is this client's turn to make a choice in the story.
virtual void onEnd (const Ending *ending)
 This method is called once if the story reaches one of its pre-defined endings.
virtual void onStop (const std::string &message)
 This method is called once when the client's session ends.
virtual void onClose ()
 This method is called once if the client was closed, if it was interrupted, or if the socket was disconnected.
virtual void onDisconnect ()
 If the client ever established its connection to the server, this method is called once right before the execute() method returns or throws an exception.
virtual void onWarning (const std::string &message)
 This method is called if this client encounters a problem which does not immediately require it to close but which may cause problems.
virtual void onError (const std::string &message)
 This method is called if the server reports an error to this client.
std::unique_ptr< Message > receiveAny ()
 Waits for a Message of any type to be received.
template<typename T>
std::unique_ptr< T > receive ()
 Waits for a Message of a specified type to be received.

Friends

std::ostream & operator<< (std::ostream &os, const Client &a)
 Override stream insertion operator to allow printing the Client class.

Detailed Description

A client connects to a server to find a partner and play a role in a storytelling session.

This abstract class implements the necessary communication protocol to connect to the server, find a partner, and start a session. Each time a status update arrives from the server that requires this client to make a choice, the onChoice method is called to determine what choice the agent wants to make.

This class provides several other methods that are all called from the same thread at important moments in the client's lifecycle. These methods can be overridden to, for example, log important information or update the client's world model. See the execute() method for a full description of these methods and when they are called.

If the session begins and ends normally the client's execute() method returns the session ID of the completed session. If this client disconnects early, or if a problem occurs that does not cause an uncaught exception, that method will return an empty string.

Author
Gage Birchmeier

Constructor & Destructor Documentation

◆ Client() [1/5]

Client::Client ( const std::string & name,
const std::string & password,
const std::string & world,
Role role,
const std::string & partner,
const char * key,
const std::string & url,
int port )

Constructs a client with the given session preferences, password, API key, and network details.

Parameters
namethe name the client will use
passwordthe password the client will provide to the server, or empty if the client will not use a password
worldthe name of the world the client wants their session to take place in, or empty if the client has no preference for a story world
rolethe role the client wants to play in the session, or NONE if the client is willing to play either role
partnerthe name of the client's desired partner, or empty if the client is willing to play with any partner
keythe API key the client will use to access external resources and computation, or empty if the client will not use the external API
urlthe URL of the server to which this client will connect
portthe network port on which this client will connect

◆ Client() [2/5]

Client::Client ( const std::string & name,
const std::string & world,
Role role,
const std::string & partner,
const std::string & url,
int port )

Constructs a client with the given session preferences and network details, reading the password and API key from the environment.

The client's password will be read from ENVIRONMENT_VARIABLE_PASSWORD. The client's API key will be read from ENVIRONMENT_VARIABLE_API_KEY.

Parameters
namethe name the client will use
worldthe name of the world the client wants their session to take place in, or empty if the client has no preference for a story world
rolethe role the client wants to play in the session, or NONE if the client is willing to play either role
partnerthe name of the client's desired partner, or empty if the client is willing to play with any partner
urlthe URL of the server to which this client will connect
portthe network port on which this client will connect

◆ Client() [3/5]

Client::Client ( const std::string & name,
const std::string & world,
Role role,
const std::string & partner )

Constructs a client with the given session preferences, reading the password and API key from the environment, and using the default network settings.

Parameters
namethe name the client will use
worldthe name of the world the client wants their session to take place in, or empty if the client has no preference for a story world
rolethe role the client wants to play in the session, or NONE if the client is willing to play either role
partnerthe name of the client's desired partner, or empty if the client is willing to play with any partner

◆ Client() [4/5]

Client::Client ( const std::string & name,
const std::string & world,
Role role )

Constructs a client with a name, role, and world name, which has no preference for a partner, reading the password and API key from the environment, and using the default network settings.

Parameters
namethe name the client will use
worldthe name of the world the client wants their session to take place in, or empty if the client has no preference for a story world
rolethe role the client wants to play in the session, or empty if the client is willing to play either role

◆ Client() [5/5]

Client::Client ( const std::string & name)

Constructs a client with a given name, which has no preference for its role, world, or partner, reading the password and API key from the environment, and using the default network settings.

Parameters
namethe name the client will use

Member Function Documentation

◆ close()

void tt::Client::close ( )

Disconnects this client from the server, causing it to stop. This method can be called safely from any thread. If this method is called before the client connects (e.g. before execute()), it does nothing.

◆ connect()

SSL * tt::Client::connect ( const std::string & url,
int port )

Establishes a secure socket to the server based on this client's network configuration.

By default, this method resolves the host name, opens a TCP connection, performs a TLS handshake using OpenSSL's TLS client method, and returns a new SSL session.

Parameters
urlthe host name or IP address of the server
portthe network port on which to open the socket
Returns
a secure connection to the server
Exceptions
std::runtime_errorif a problem occurred establishing the socket, connecting to the server, or completing the TLS handshake
std::invalid_argumentif the URL of the server cannot be resolved
std::invalid_argumentif the network port is outside the specified range of valid port values

◆ execute()

std::string tt::Client::execute ( )

This method connects to the server, joins, waits for a session to start, sends the choices made by this client, and eventually returns the session ID of the completed session.

As this method runs, it calls other methods to notify the client of important events. Some of these methods are guaranteed to be called even if an exception is thrown. The list of those methods and when they happen is as follows:

  • The connect method is called to establish a secure socket to the server. If an exception is thrown by this method, it will be thrown immediately, and the rest of the methods below will not be called.
  • After the client receives the connect message from the server, onConnect is called. This is the client's last chance to make changes to its identity or session details.
  • After the client receives the start message and the first update message, the session begins and the onStart method is called. Immediately before that method is called, methods like getWorld will be able to return their values.
  • Each time the client receives an update message, the onUpdate method is called to notify the client about changes to the session history and world state. This method is called whether or not the client needs to make a choice.
  • Each time the client receives an update message and it is the client's turn to act, after calling onUpdate the onChoice method will be called to solicit which turn the client wants to take. After calling that method, the getChoices method will return an empty list.
  • If the session's story reaches one of its pre-defined endings, the onEnd method will be called.
  • If the session ended because this client was closed, because the client thread was interrupted, or because the socket was disconnected, the onClose method will be called. If an exception was thrown earlier in this method, onClose will not be called.
  • If the session started, the onStop method will always be called before this method returns or throw an exception.
  • If the client successfully connected to the server, the onDisconnect method will always be called before this method returns or throws an exception.

◆ getChoices()

std::vector< const Turn * > tt::Client::getChoices ( ) const

If it is currently this client's turn to act, this method returns the list of turns they can take next.

If it is not the client's turn, the list will be empty.

Returns
the list of turns the client can take next
Exceptions
std::logic_errorif the client's session has not yet started

◆ getHistory()

std::vector< const Turn * > tt::Client::getHistory ( ) const

Returns the list of all turns that have been taken so far in this client's session that this client has observed.

If the client is the game master, they always observe all turns. If this client is the player, they may not observe all turns.

Returns
the list of all turns that have been taken so far in the session
Exceptions
std::logic_errorif the client's session has not yet started

◆ getName()

const std::string & tt::Client::getName ( ) const

Returns the client's name.

Returns
the client's name

◆ getPartner()

const std::string & tt::Client::getPartner ( ) const

Returns the name of the partner this client wants to play with.

An empty value means this client is willing to play with any partner. This value does not change when the session starts. In other words, if the client did not request a specific partner, the client has no way to know the name of the partner they were assigned.

Returns
the name of the partner this client wants to play with

◆ getRole()

Role tt::Client::getRole ( ) const

Returns the role this client wants to play or is currently playing in its session.

The NONE value means this client's session has not yet started and this client is willing to play either role. Once the session starts, this method will return the role assigned to the client.

Returns
the client's role

◆ getSession()

const std::string & tt::Client::getSession ( )

Returns the ID of this client's session.

A session is only assigned after the session has ended, so the value returned by this method will always be empty until the very end of this client's lifecycle.

Returns
the session ID of this client's session

◆ getState()

const State * tt::Client::getState ( ) const

Returns the current state of the story world.

Returns
the current state of the story world
Exceptions
std::logic_errorif the client's session has not yet started

◆ getWorld()

const World * tt::Client::getWorld ( )

Returns a const pointer to the story world in which this client's session is taking place.

Returns
the story world for this client's session
Exceptions
std::logic_errorif the client's session has not yet started

◆ getWorldName()

const std::string & tt::Client::getWorldName ( ) const

Returns the name of the story world this client will play in or is currently playing in.

An empty value means this client's session has not yet started and this client is willing to play in any world. Once the session starts, this method will return the name of the world the client is playing in.

Returns
the name of the client's story world

◆ onChoice()

virtual int tt::Client::onChoice ( const Status * status)
protectedpure virtual

This method is called each time it is this client's turn to make a choice in the story.

Calls to this method will always be preceded by a call to onStart if this is the start of the session or onUpdate if this is not the start of the session.

Parameters
statusthe current status of the story world, including the history of all turns so far, the current state of the world, and the list of choices available for the client to choose from
Returns
the index (starting at 0) of the turn this client wants to take from the list of choices given

◆ onClose()

virtual void tt::Client::onClose ( )
inlineprotectedvirtual

This method is called once if the client was closed, if it was interrupted, or if the socket was disconnected.

This method will not be called if the client is stopping because an uncaught exception was thrown at an earlier stage of the client's lifecycle. This method is always called from the execute() method, meaning it will always run on the thread which called that method, even if a different thread called the close method.

By default, this method does nothing. It can be overridden if the client wants to react to being closed.

◆ onConnect()

virtual void tt::Client::onConnect ( const Connect * connect)
inlineprotectedvirtual

This method is called after the client connects to the server and the server sends the list of available worlds and agents.

This method is typically the last chance the client has to change its identity, such as its name or requested role, before the client's join request is sent.

By default, this method does nothing. It can be overridden if the client wants to react to connecting to the server.

Parameters
connectthe connect message sent from the server

◆ onDisconnect()

virtual void tt::Client::onDisconnect ( )
inlineprotectedvirtual

If the client ever established its connection to the server, this method is called once right before the execute() method returns or throws an exception.

By default, this method does nothing. It can be overridden if the client wants to react to the end of its lifecycle. This is a good method to clean up resources.

◆ onEnd()

virtual void tt::Client::onEnd ( const Ending * ending)
inlineprotectedvirtual

This method is called once if the story reaches one of its pre-defined endings.

If the session never starts or if the story does not reach an ending, this method will not be called.

By default, this method does nothing. It can be overridden if the client wants to react to the end of the story.

Parameters
endingthe ending of the story

◆ onError()

void tt::Client::onError ( const std::string & message)
protectedvirtual

This method is called if the server reports an error to this client.

By default, if the session has not yet started, this method throws a std::runtime_error whose message is the message passed to this method. If the session has started, the error will be printed to standard error and no exception will be thrown.

Parameters
messagean explanation of what caused the error

◆ onStart()

virtual void tt::Client::onStart ( const World * world,
Role role,
const State * initial )
inlineprotectedvirtual

This method is called once when the client's session starts.

By default, this method does nothing. It can be overridden if the client wants to react to its session starting.

Parameters
worldthe story world in which the session will take place
rolethe role this client will play in the story
initialthe initial state of the story world before the story begins

◆ onStop()

virtual void tt::Client::onStop ( const std::string & message)
inlineprotectedvirtual

This method is called once when the client's session ends.

If the session started, this method will always be called, even if an uncaught exception was thrown at an earlier stage in the client's lifecycle.

By default, this method does nothing. It can be overridden if the client wants to react to the end of the session.

Parameters
messagethe message explaining why the session ended, or null if no explanation was received

◆ onUpdate()

virtual void tt::Client::onUpdate ( const Status * status)
inlineprotectedvirtual

This method is called each time the story world changes as a result of a turn the client observes.

If this client is the game master, it will observe all turns. If this client is the player, it may not observe all turns.

By default, this method does nothing. It can be overridden if the client wants to react to a change in the world state.

Parameters
statusthe current status of the story world, including the history of all turns and the current world state

◆ onWarning()

void tt::Client::onWarning ( const std::string & message)
protectedvirtual

This method is called if this client encounters a problem which does not immediately require it to close but which may cause problems.

By default, this method prints the warning to standard error

Parameters
messagea description of the problem

◆ receive()

template<typename T>
std::unique_ptr< T > tt::Client::receive ( )
protected

Waits for a Message of a specified type to be received.

Throws an error if any other type is received instead.

It is not recommended for implementations of this abstract class to call this function.

Parameters
<T>the type of Message to wait for
Returns
a unique_ptr to the message received
Exceptions
std::runtime_errorif the received message is of the wrong type

◆ receiveAny()

std::unique_ptr< Message > tt::Client::receiveAny ( )
protected

Waits for a Message of any type to be received.

It is not recommended for implementations of this abstract class to call this function.

Returns
a unique_ptr to the message received.

◆ sendMessage()

void tt::Client::sendMessage ( const tt::Message & m)

This method sends a message to the server.

It is usually unsafe for implementations of this abstract class to call this method. The execute() method has specific expectations about when and what type of messages should be sent. Calling this method at an unexpected time is likely to cause this client to get out of sync with the server.

Parameters
mthe message to send to the server
Exceptions
std::logic_errorif the client has not yet connected to the server

◆ setName()

void tt::Client::setName ( const std::string & name)
protected

Sets the name this client will use.

Parameters
namethe new name this client will use
Exceptions
std::logic_errorif the client has already joined the server

◆ setPartner()

void tt::Client::setPartner ( const std::string & partner)
protected

Sets the name of the partner this client wants to play in its session.

Parameters
partnerthe name of the partner this client wants to play with
Exceptions
std::logic_errorif the client has already joined the server

◆ setPassword()

void tt::Client::setPassword ( const std::string & password)
protected

Sets the password this client will use.

Parameters
passwordthe new password this client will use
Exceptions
std::logic_errorif the client has already joined the server

◆ setRole()

void tt::Client::setRole ( Role role)
protected

Sets the role this client wants to play in its session.

Parameters
rolethe role this client wants to play in its session
Exceptions
std::logic_errorif the client has already joined the server

◆ setWorldName()

void tt::Client::setWorldName ( const std::string & world)
protected

Sets the name of the story world this client wants to play in.

Parameters
worldthe name of the world this client wants to play in
Exceptions
std::logic_errorif the client has already joined the server

◆ toString()

std::string tt::Client::toString ( ) const
virtual

Gives a string representation of this client.

Returns
a string representation of this client.

◆ operator<<

std::ostream & operator<< ( std::ostream & os,
const Client & a )
friend

Override stream insertion operator to allow printing the Client class.

Parameters
osan output stream to insert into
aa reference to a client object
Returns
the output stream referenced

Member Data Documentation

◆ ENVIRONMENT_VARIABLE_API_KEY

const std::string Client::ENVIRONMENT_VARIABLE_API_KEY = "apikey"
static

The name of the environment variable where the client expects to find the API key used to authenticate with the service that provides functions which require special external resources or computation.

If this environment variable is not set and no API key is provided in the constructor, this agent will not be able to use the external API.

◆ ENVIRONMENT_VARIABLE_PASSWORD

const std::string Client::ENVIRONMENT_VARIABLE_PASSWORD = "password"
static

The name of the environment variable where the client expects to find the password this agent will use, unless the password is explicitly set by the agent's constructor.

If this environment variable is not set and no password is provided in the constructor, this agent will not use a password.


The documentation for this class was generated from the following files: