|
TT Client Library 1.0.0
C++ library for Tandem Tales clients.
|
A client connects to a server to find a partner and play a role in a storytelling session.
More...
#include <tt/Client.h>

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. | |
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.
| 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.
| name | the name the client will use |
| password | the password the client will provide to the server, or empty if the client will not use a password |
| world | the 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 |
| role | the role the client wants to play in the session, or NONE if the client is willing to play either role |
| partner | the name of the client's desired partner, or empty if the client is willing to play with any partner |
| key | the API key the client will use to access external resources and computation, or empty if the client will not use the external API |
| url | the URL of the server to which this client will connect |
| port | the network port on which this client will connect |
| 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.
| name | the name the client will use |
| world | the 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 |
| role | the role the client wants to play in the session, or NONE if the client is willing to play either role |
| partner | the name of the client's desired partner, or empty if the client is willing to play with any partner |
| url | the URL of the server to which this client will connect |
| port | the network port on which this client will connect |
| 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.
| name | the name the client will use |
| world | the 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 |
| role | the role the client wants to play in the session, or NONE if the client is willing to play either role |
| partner | the name of the client's desired partner, or empty if the client is willing to play with any partner |
| 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.
| name | the name the client will use |
| world | the 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 |
| role | the role the client wants to play in the session, or empty if the client is willing to play either role |
| 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.
| name | the name the client will use |
| 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.
| 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.
| url | the host name or IP address of the server |
| port | the network port on which to open the socket |
| std::runtime_error | if a problem occurred establishing the socket, connecting to the server, or completing the TLS handshake |
| std::invalid_argument | if the URL of the server cannot be resolved |
| std::invalid_argument | if the network port is outside the specified range of valid port values |
| 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:
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. connect message from the server, onConnect is called. This is the client's last chance to make changes to its identity or session details. 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. 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. 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. onEnd method will be called. 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. onStop method will always be called before this method returns or throw an exception. onDisconnect method will always be called before this method returns or throws an exception. | 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.
| std::logic_error | if the client's session has not yet started |
| 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.
| std::logic_error | if the client's session has not yet started |
| const std::string & tt::Client::getName | ( | ) | const |
Returns the client's name.
| 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.
| 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.
| 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.
| const State * tt::Client::getState | ( | ) | const |
Returns the current state of the story world.
| std::logic_error | if the client's session has not yet started |
| const World * tt::Client::getWorld | ( | ) |
Returns a const pointer to the story world in which this client's session is taking place.
| std::logic_error | if the client's session has not yet started |
| 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.
|
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.
| status | the 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 |
list of choices given
|
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.
|
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.
| connect | the connect message sent from the server |
|
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.
|
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.
| ending | the ending of the story |
|
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.
| message | an explanation of what caused the error |
|
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.
| world | the story world in which the session will take place |
| role | the role this client will play in the story |
| initial | the initial state of the story world before the story begins |
|
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.
| message | the message explaining why the session ended, or null if no explanation was received |
|
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.
| status | the current status of the story world, including the history of all turns and the current world state |
|
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
| message | a description of the problem |
|
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.
| <T> | the type of Message to wait for |
| std::runtime_error | if the received message is of the wrong type |
|
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.
| 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.
| m | the message to send to the server |
| std::logic_error | if the client has not yet connected to the server |
|
protected |
Sets the name this client will use.
| name | the new name this client will use |
| std::logic_error | if the client has already joined the server |
|
protected |
Sets the name of the partner this client wants to play in its session.
| partner | the name of the partner this client wants to play with |
| std::logic_error | if the client has already joined the server |
|
protected |
Sets the password this client will use.
| password | the new password this client will use |
| std::logic_error | if the client has already joined the server |
|
protected |
Sets the role this client wants to play in its session.
| role | the role this client wants to play in its session |
| std::logic_error | if the client has already joined the server |
|
protected |
Sets the name of the story world this client wants to play in.
| world | the name of the world this client wants to play in |
| std::logic_error | if the client has already joined the server |
|
virtual |
Gives a string representation of this client.
|
friend |
Override stream insertion operator to allow printing the Client class.
| os | an output stream to insert into |
| a | a reference to a client object |
|
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.
|
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.