/**
 * @file   lleventapi.h
 * @author Nat Goodspeed
 * @date   2009-10-28
 * @brief  LLEventAPI is the base class for every class that wraps a C++ API
 *         in an event API
 * (see https://wiki.lindenlab.com/wiki/Incremental_Viewer_Automation/Event_API).
 *
 * $LicenseInfo:firstyear=2009&license=viewerlgpl$
 * Second Life Viewer Source Code
 * Copyright (C) 2010, Linden Research, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License only.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 * $/LicenseInfo$
 */

#if ! defined(LL_LLEVENTAPI_H)
#define LL_LLEVENTAPI_H

#include "lleventdispatcher.h"
#include "llinstancetracker.h"
#include <string>

namespace LL
{
    class LazyEventAPIParams;
}

/**
 * LLEventAPI not only provides operation dispatch functionality, inherited
 * from LLDispatchListener -- it also gives us event API introspection.
 * Deriving from LLInstanceTracker lets us enumerate instances.
 */
class LL_COMMON_API LLEventAPI: public LLDispatchListener,
                  public LLInstanceTracker<LLEventAPI, std::string>
{
    typedef LLDispatchListener lbase;
    typedef LLInstanceTracker<LLEventAPI, std::string> ibase;

public:

    /**
     * @param name LLEventPump name on which this LLEventAPI will listen. This
     * also serves as the LLInstanceTracker instance key.
     * @param desc Documentation string shown to a client trying to discover
     * available event APIs.
     * @param field LLSD::Map key used by LLDispatchListener to look up the
     * subclass method to invoke [default "op"].
     */
    LLEventAPI(const std::string& name, const std::string& desc, const std::string& field="op");
    virtual ~LLEventAPI();

    /// Get the string name of this LLEventAPI
    std::string getName() const { return ibase::getKey(); }
    /// Get the documentation string
    std::string getDesc() const { return mDesc; }

    /**
     * Instantiate a Response object in any LLEventAPI subclass method that
     * wants to guarantee a reply (if requested) will be sent on exit from the
     * method. The reply will be sent if request.has(@a replyKey), default
     * "reply". If specified, the value of request[replyKey] is the name of
     * the LLEventPump on which to send the reply. Conventionally you might
     * code something like:
     *
     * @code
     * void MyEventAPI::someMethod(const LLSD& request)
     * {
     *     // Send a reply event as long as request.has("reply")
     *     Response response(LLSD(), request);
     *     // ...
     *     // will be sent in reply event
     *     response["somekey"] = some_data;
     * }
     * @endcode
     */
    class LL_COMMON_API Response
    {
    public:
        /**
         * Instantiating a Response object in an LLEventAPI subclass method
         * ensures that, if desired, a reply event will be sent.
         *
         * @a seed is the initial reply LLSD that will be further decorated before
         * being sent as the reply
         *
         * @a request is the incoming request LLSD; we particularly care about
         * [replyKey] and ["reqid"]
         *
         * @a replyKey [default "reply"] is the string name of the LLEventPump
         * on which the caller wants a reply. If <tt>(!
         * request.has(replyKey))</tt>, no reply will be sent.
         */
        Response(const LLSD& seed, const LLSD& request, const LLSD::String& replyKey="reply");
        ~Response();

        /**
         * @code
         * if (some condition)
         * {
         *     response.warn("warnings are logged and collected in [\"warnings\"]");
         * }
         * @endcode
         */
        void warn(const std::string& warning);
        /**
         * @code
         * if (some condition isn't met)
         * {
         *     // In a function returning void, you can validly 'return
         *     // expression' if the expression is itself of type void. But
         *     // returning is up to you; response.error() has no effect on
         *     // flow of control.
         *     return response.error("error message, logged and also sent as [\"error\"]");
         * }
         * @endcode
         */
        void error(const std::string& error);

        /**
         * set other keys...
         *
         * @code
         * // set any attributes you want to be sent in the reply
         * response["info"] = some_value;
         * // ...
         * response["ok"] = went_well;
         * @endcode
         */
        LLSD& operator[](const LLSD::String& key) { return mResp[key]; }

         /**
         * set the response to the given data
         */
        void setResponse(LLSD const & response){ mResp = response; }

        LLSD mResp, mReq;
        LLSD::String mKey;
    };

protected:
    // constructor used only by subclasses registered by LazyEventAPI
    LLEventAPI(const LL::LazyEventAPIParams&);

private:
    std::string mDesc;
};

#endif /* ! defined(LL_LLEVENTAPI_H) */