/**
 * @file   llleap.h
 * @author Nat Goodspeed
 * @date   2012-02-20
 * @brief  Class that implements "LLSD Event API Plugin"
 *
 * $LicenseInfo:firstyear=2012&license=viewerlgpl$
 * Copyright (c) 2012, Linden Research, Inc.
 * $/LicenseInfo$
 */

#if ! defined(LL_LLLEAP_H)
#define LL_LLLEAP_H

#include "llinstancetracker.h"
#include "llexception.h"
#include "llprocess.h"
#include <string>
#include <vector>

/**
 * LLSD Event API Plugin class. Because instances are managed by
 * LLInstanceTracker, you can instantiate LLLeap and forget the instance
 * unless you need it later. Each instance manages an LLProcess; when the
 * child process terminates, LLLeap deletes itself. We don't require a unique
 * LLInstanceTracker key.
 *
 * The fact that a given LLLeap instance vanishes when its child process
 * terminates makes it problematic to store an LLLeap* anywhere. Any stored
 * LLLeap* pointer should be validated before use by
 * LLLeap::getInstance(LLLeap*) (see LLInstanceTracker).
 */
class LL_COMMON_API LLLeap: public LLInstanceTracker<LLLeap>
{
public:

    /**
     * Pass a brief string description, mostly for logging purposes. The desc
     * need not be unique, but obviously the clearer we can make it, the
     * easier these things will be to debug. The strings are the command line
     * used to launch the desired plugin process.
     *
     * Pass exc=false to suppress LLLeap::Error exception. Obviously in that
     * case the caller cannot discover the nature of the error, merely that an
     * error of some kind occurred (because create() returned NULL). Either
     * way, the error is logged.
     */
    static LLLeap* create(const std::string& desc, const std::vector<std::string>& plugin,
                          bool exc=true);

    /**
     * Pass a brief string description, mostly for logging purposes. The desc
     * need not be unique, but obviously the clearer we can make it, the
     * easier these things will be to debug. Pass a command-line string
     * to launch the desired plugin process.
     *
     * Pass exc=false to suppress LLLeap::Error exception. Obviously in that
     * case the caller cannot discover the nature of the error, merely that an
     * error of some kind occurred (because create() returned NULL). Either
     * way, the error is logged.
     */
    static LLLeap* create(const std::string& desc, const std::string& plugin,
                          bool exc=true);

    /**
     * Pass an LLProcess::Params instance to specify desc, executable, args et al.
     *
     * Note that files and postend are set implicitly; any values you set in
     * those fields will be disregarded.
     *
     * Pass exc=false to suppress LLLeap::Error exception. Obviously in that
     * case the caller cannot discover the nature of the error, merely that an
     * error of some kind occurred (because create() returned NULL). Either
     * way, the error is logged.
     */
    static LLLeap* create(const LLProcess::Params& params, bool exc=true);

    /**
     * Exception thrown for invalid create() arguments, e.g. no plugin
     * program. This is more resiliant than an LL_ERRS failure, because the
     * string(s) passed to create() might come from an external source. This
     * way the caller can catch LLLeap::Error and try to recover.
     */
    struct Error: public LLException
    {
        Error(const std::string& what): LLException(what) {}
    };

    virtual ~LLLeap();

protected:
    LLLeap();
};

#endif /* ! defined(LL_LLLEAP_H) */