NOTE: this documentation talks a lot about "clients" and "servers".
More...
|
Classes | |
| class | converse::ConversationHost |
| anyone that wants to start a conversation must supply one of these. More... | |
| class | converse::ConversationRouter |
| Object that knows how to route conversation dialogs. More... | |
| class | converse::ConversationManager |
| object that manages conversations on the server This object must be threadsafe! More... | |
Typedefs | |
| typedef dword_t | converse::conn_id_t |
| The connection ID used by the Conversation library is used for validation (client can ensure that only the proper endpoint is participating in conversations) but is otherwise not used. | |
Functions | |
| virtual int | converse::ConversationHost::getCurrentDialogIdTS (void)=0 |
| The host should return the current dialog ID -- 0 to end. | |
| virtual void | converse::ConversationHost::handleReplyTS (IN int dialogId, IN const Datahash *reply)=0 |
| This method is called when the player has completed a given dialog and has sent the reply back to the ConversationManager. | |
| virtual std::string | converse::ConversationHost::getDialogDataTS (void)=0 |
| Host should return the raw dialog data for the current dialog ID (dialog data is a text string -- see Dialog Library). | |
| virtual bool | converse::ConversationManager::updateConversationTS (IN const char *guid, IN conn_id_t connId, IN int playerId, IN smart_ptr< ConversationHost > host)=0 |
| virtual bool | converse::ConversationManager::handleDialogReplyTS (IN const char *guid, IN int dialogId, IN conn_id_t connId, IN int playerId, IN const Datahash *reply)=0 |
| virtual void | converse::ConversationManager::updateAll (void)=0 |
|
| |
| virtual bool | converse::ConversationHost::updateState (void) |
| This is called "frequently", on the order of 100 times/second, although no particular rate is guaranteed. | |
| virtual | converse::ConversationRouter::~ConversationRouter (void) throw () |
| cannot delete through this interface! | |
| static smart_ptr < ConversationManager > | converse::ConversationManager::create (IN ConversationRouter *router) |
| virtual | converse::ConversationHost::~ConversationHost (void) throw () |
Detailed Description
NOTE: this documentation talks a lot about "clients" and "servers".
That's because the original implementation was in fact designed with a particular remote client/server use case in mind. However, the concept has broadened significantly since then. At this point, the Conversation Library is a convenient way to help the user through multiple dialogs related to a particular task (signing into a remote server, configuration local hardware, etc.). The library also has a few concepts (unique IDs and central state management) that makes it easer to drive dialogs remotely, but many use cases involve the client (user-displayed dialogs) and server (conversation management) all on the same machine.
This library helps track conversations (chains of dialogs) but does not manage any rendering itself! That is up to the client.
A Conversation is a long-running communication channel between the server and a player. The concept of a Conversation exists so that client machines can be sure to keep in sync even during network or other communication drops.
Some properties of Conversations:
- Only the server can initiate Conversations. Clients can sometimes request that conversations be started, but that is usually as part of specific message protocols and is not a general capability.
- Conversations are only between the server and human players.
- The server maintains all state for a given Conversation.
The fact that Conversations are between the server and human players means that the contents of conversations are always Dialogs (see Dialog Library). The server will always send dialogs to the player, and the player will always send dialog responses back to the server.
Just as Dialogs can be thought of as HTML pages (or forms), a Conversation can be thought of as a series of forms. The ConversationManager helps coordinate general state and flow of a player moving through a series of forms, and the ConversationHost object manages form handling for the specific conversation.
The fact that only the server can initiate Conversations, and maintains all Conversation state, helps minimize race conditions and makes synchronization easy. As a consequence, however, all clients should be aware that they may have stale Conversation state and should occasionally refresh (to pick up any new conversations they missed), and pay attention to return codes in case their local view of a particular conversation is out-of-date.
Clients may receive duplicate messages about a conversation, and so should de-dupe messages based on the conversation and dialog GUIDs supplied. The server's latest message should be considered authoritative if the client discovers that the server's dialog ID is different than the local dialog ID for a given conversation.
Note that conversations must have a globally unique identifier (GUID). Dialog identifiers are only unique within a particular conversation, and so dialogs just have regular IDs (no need to be globally unique). Hence the key variables conversationGuid (globally-unique conversation identifier) and dialogId (identifier for dialog that is unique within the context of a particular conversation).
A player may have multiple conversations going at once! For instance, they may be conversing with another player in one, buying items from a shop in another, and overhearing other people talking nearby in another. However, a given conversation will only have one dialog active at any one time.
There are three main objects in the Conversation data model:
- ConversationManager : manages high-level conversation state for all conversations currently underway.
- ConversationHost : manages dialog state for a particular conversation
- ConversationRouter : knows how to get dialogs presented to the player.
Host objects are the most common objects, since any kind of conversation (player joining a game, chat, local system menus, buying from a shop) will require a dedicated host.
Hosts do not need to know how to get the dialogs passed over the network or displayed to the client. The ConversationRouter will do that. On the server, the ConversationRouter knows how to send dialog messages over the network. On the client, the ConversationRouter can get them displayed.
Although we say "Conversations are between the server and a player", conversations can also be run on the client. This is helpful to present the player with local dialogs such as system menus etc. In this case, the client often runs its own ConversationManager with a local ConversationRouter.
Typedef Documentation
| typedef dword_t converse::conn_id_t |
The connection ID used by the Conversation library is used for validation (client can ensure that only the proper endpoint is participating in conversations) but is otherwise not used.
This library makes no networking calls, for instance.
Definition at line 146 of file conversation.h.
Function Documentation
| virtual int converse::ConversationHost::getCurrentDialogIdTS | ( | void | ) | [pure virtual, inherited] |
The host should return the current dialog ID -- 0 to end.
| virtual void converse::ConversationHost::handleReplyTS | ( | IN int | dialogId, | |
| IN const Datahash * | reply | |||
| ) | [pure virtual, inherited] |
This method is called when the player has completed a given dialog and has sent the reply back to the ConversationManager.
The Manager forwards the reply to the host so it can take a look at the reply and figure out the next step. After this, the host will be called on getCurrentDialogIdTS() so the conversation can continue.
| virtual std::string converse::ConversationHost::getDialogDataTS | ( | void | ) | [pure virtual, inherited] |
Host should return the raw dialog data for the current dialog ID (dialog data is a text string -- see Dialog Library).
| bool converse::ConversationHost::updateState | ( | void | ) | [virtual, inherited] |
This is called "frequently", on the order of 100 times/second, although no particular rate is guaranteed.
The Host should update internal state as necessary, and return true if the Host would like the client to refresh its view of the conversation. Default implementation simply returns false.
Definition at line 54 of file conversation.cpp.
| converse::ConversationRouter::~ConversationRouter | ( | void | ) | throw () [protected, virtual, inherited] |
cannot delete through this interface!
Definition at line 42 of file conversation.cpp.
| virtual bool converse::ConversationManager::updateConversationTS | ( | IN const char * | guid, | |
| IN conn_id_t | connId, | |||
| IN int | playerId, | |||
| IN smart_ptr< ConversationHost > | host | |||
| ) | [pure virtual, inherited] |
| virtual bool converse::ConversationManager::handleDialogReplyTS | ( | IN const char * | guid, | |
| IN int | dialogId, | |||
| IN conn_id_t | connId, | |||
| IN int | playerId, | |||
| IN const Datahash * | reply | |||
| ) | [pure virtual, inherited] |
| virtual void converse::ConversationManager::updateAll | ( | void | ) | [pure virtual, inherited] |
| smart_ptr< ConversationManager > converse::ConversationManager::create | ( | IN ConversationRouter * | router | ) | [static, inherited] |
Definition at line 401 of file conversation.cpp.
| converse::ConversationHost::~ConversationHost | ( | void | ) | throw () [virtual, inherited] |
Definition at line 41 of file conversation.cpp.
