conversation.h

Go to the documentation of this file.

/*
 * conversation.h
 *
 * Copyright (C) 2007,2009,2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef WAVEPACKET_CONVERSATION_H__
#define WAVEPACKET_CONVERSATION_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "threadsafe/smart_ptr.h"


// forward declarations
class Datahash;


namespace converse {

////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup lib
/// \defgroup conversation Conversation Library
///
/// \n
/// \b 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.
///
/// \n
/// 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 \ref dialog).
/// 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.
///
/// \n
/// 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.
///
/// \n
/// 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.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// 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.
typedef dword_t conn_id_t;


/// anyone that wants to start a conversation must supply one of these.
/// Note that all methods must be threadsafe!
class ConversationHost {
public:
        // virtual destructor --------------------------------------------------
        virtual ~ConversationHost(void) throw();

        // converse::ConversationHost class interface methods ------------------

        /// The host should return the current dialog ID -- 0 to end
        virtual int getCurrentDialogIdTS(void) = 0;

        /// 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 void handleReplyTS(IN int dialogId,
                                IN const Datahash * reply) = 0;

        /// Host should return the raw dialog data for the current dialog ID
        /// (dialog data is a text string -- see \ref dialog).
        virtual std::string getDialogDataTS(void) = 0;

        /// 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.
        virtual bool updateState(void);
};



/// Object that knows how to route conversation dialogs.  On the server, this
/// object knows how to send dialogs over the network.  On the client, this
/// object knows how to render local dialogs.  Clients must supply this.
/// Must be threadsafe!
class ConversationRouter {
public:
        // converse::ConversationRouter class interface methods ----------------
        virtual void routeConversationTS(IN const char * guid,
                                IN int dialogId,
                                IN int playerId,
                                IN conn_id_t connId,
                                IN const char * dialogData) = 0;

protected:
        // virtual destructor --------------------------------------------------
        /// cannot delete through this interface!
        virtual ~ConversationRouter(void) throw();
};



/// object that manages conversations on the server
/// This object must be threadsafe!
class ConversationManager {
public:
        // virtual destructor --------------------------------------------------
        virtual ~ConversationManager(void) throw();

        // converse::ConversationManager class interface methods ---------------
        virtual bool updateConversationTS(IN const char * guid,
                                IN conn_id_t connId,
                                IN int playerId,
                                IN smart_ptr<ConversationHost> host) = 0;

        virtual bool handleDialogReplyTS(IN const char * guid,
                                IN int dialogId,
                                IN conn_id_t connId,
                                IN int playerId,
                                IN const Datahash * reply) = 0;

        virtual void updateAll(void) = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<ConversationManager> create(
                                IN ConversationRouter * router);
};



};      // converse namespace

#endif  // WAVEPACKET_CONVERSATION_H__