plugin_handle_impl.hpp

来自「ncbi源码」· HPP 代码 · 共 264 行

/*
 * ===========================================================================
 * PRODUCTION $Log: plugin_handle_impl.hpp,v $
 * PRODUCTION Revision 1000.4  2004/06/01 20:44:28  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.12
 * PRODUCTION
 * ===========================================================================
 */

#ifndef GUI_CORE___PLUGIN_HANDLE_IMPL__HPP
#define GUI_CORE___PLUGIN_HANDLE_IMPL__HPP

/*  $Id: plugin_handle_impl.hpp,v 1000.4 2004/06/01 20:44:28 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Mike DiCuccio
 *
 * File Description:
 *
 */

#include <gui/core/plugin_handle.hpp>

#include <gui/plugin/PluginInfo.hpp>
#include <gui/plugin/PluginLibInfo.hpp>
#include <gui/plugin/PluginArgSet.hpp>

BEGIN_NCBI_SCOPE
USING_SCOPE(objects);

class CPluginFactoryBase;
class CPluginBase;


//
// class CPluginHandle_Impl hides the details of implementing load-on-demand.
//
class CPluginHandle_Impl : public CObject
{
    friend class CPluginRegistry;
public:

    CPluginHandle_Impl(const CPluginLibInfo& info);
    virtual ~CPluginHandle_Impl();

    // retrieve a plugin handle representing this implementation
    CPluginHandle GetHandle(void) const;

    // retrieve the command type this plugin supports
    CPluginCommandSet::E_Choice GetCommand(void) const;

    // determine if a given command sub-type is supported by this plugin
    bool HasCommandSubtype(EAlgoCommand) const;
    bool HasCommandSubtype(EDataCommand) const;
    bool HasCommandSubtype(EViewCommand) const;

    // determine if this plugin has been loaded yet
    bool    IsLoaded(void) const;

    // retrieve the enabled flag
    bool    IsEnabled(void) const;

    // fill in a default set of arguments for the specified algorithm command
    bool FillDefaults(EAlgoCommand cmd, CPluginCommand& args) const;

    // fill in a default set of arguments for the specified data command
    bool FillDefaults(EDataCommand cmd, CPluginCommand& args) const;

    // fill in a default set of arguments for the specified view command
    bool FillDefaults(EViewCommand cmd, CPluginCommand& args) const;

    // return a properly formatted CPluginMessage object to invoke this
    // plugin
    CRef<objects::CPluginMessage> CreateMessage(objects::EAlgoCommand cmd);
    CRef<objects::CPluginMessage> CreateMessage(objects::EDataCommand cmd);
    CRef<objects::CPluginMessage> CreateMessage(objects::EViewCommand cmd);

    // execute a command contained in a plugin message.  This will execute
    // the command in the specified named context; if the context doesn't
    // exist, one will be marshalled.
    void Execute(CPluginMessage& msg);

    // finalize the arguments
    void FinalizeArgs(objects::CPluginMessage& msg);

    // get the plugin info
    const CPluginInfo& GetInfo(void) const;

    // get the plugin libinfo
    const CPluginLibInfo& GetLibInfo(void) const;

    // get the name of the class this plugin exports for a given command
    const string& GetClassName(void) const;

    // retrieve the help file for a given command.  This can either be a file
    // on disk or the help itself. It does not necessarily return what's in the
    // info structure for the plugin. Instead, it uses PluginInfo.Help_file
    // to create a URL, based on the contents of the config [Help].
    //
    // The data returned by PluginInfo.GetHelp_file is an
    // expression that resolves to a URL. The resolution process
    // is as follows:
    //
    // 1. If it's an "http://" URL, then the result is simply the URL.
    //
    // 2. If it's a word, append that word to the value of 
    //    the config variable [Help]/HELP_BASE, with a slash
    //    between. 
    //
    // 3. If it's empty, use HELP_BASE + a slash + the class name with
    //    underscores removed.
    //
    // In the cases of (2) and (3), if HELP_BASE is not set,
    // then the method uses a default URL (within NCBI).
    //
    // Examples:
    //   1. Help text: http://ncbi.nlm.nih.gov/BLAST-help
    //	Resolves to: http://ncbi.nlm.nih.gov/BLAST-help
    //
    //   2. Help text: NetBLASTReply
    //	In config file: [Help]
    //			HELP_BASE=http://genomeworkbench.org/help
    //      Resolves to: http://genomeworkbench.org/help/NetBLASTReply
    //	
    //   3. Help text in class CAlgoPlugin_MyPlugin: ""
    //	In config file: [Help]
    //			HELP_BASE=http://genomeworkbench.org/help
    //      Resolves to: http://genomeworkbench.org/help/CAlgoPluginMyPlugin
    //  Note that in example #3 there are no underscores in the URL.
    //
    //
    //
    const string GetHelpFile (void) const;

    // retrieve the name of the library this plugin lives in
    const string& GetLibrary  (void) const;

    // retrieve the menu item for this plugin
    const string& GetMenuItem (void) const;

    // retrieve the mouse-over tooltip for this menu item
    const string& GetToolTip  (void) const;

    // retrieve the version information for this plugin
    int           GetVerMajor    (void) const;
    int           GetVerMinor    (void) const;
    int           GetVerRevision (void) const;
    const string& GetVerBuildDate(void) const;

protected:

    // internal command to set the factory.  This is called from the registry
    // when a plugin library is loaded.
    void x_SetFactory(CPluginFactoryBase* factory) const;
    CPluginBase* x_GetPlugin(const string& context = "");

private:
    // Our original argument information.  This is the set that we use
    // to define what we are and how we interact with the framework.
    CConstRef<CPluginLibInfo> m_Info;

    // Our working set of information.  This set may be updated as the
    // application proceeds.  Its use is primarily in FillDefaults() and
    // SetDefaults(), where it is used to define the last known set of
    // arguments.
    mutable CRef<CPluginLibInfo> m_WorkingInfo;

    // the factory we represent.  This is initially NULL; it is set when the
    // plugin is loaded
    mutable CPluginFactoryBase*     m_Factory;

    // a dictionary of named instances of the plugin that we manage
    typedef map<string, CRef<CPluginBase> > TPluginDict;
    TPluginDict m_PluginDict;

    // wrapper to retrieve the current working set
    CPluginLibInfo& x_GetWorkingSet(void) const;
};


// comparison operator for plugin handles
inline
bool operator< (const CPluginHandle_Impl& h1, const CPluginHandle_Impl& h2)
{
    return (h1.GetClassName() < h2.GetClassName());
}


END_NCBI_SCOPE


/*
 * ===========================================================================
 * $Log: plugin_handle_impl.hpp,v $
 * Revision 1000.4  2004/06/01 20:44:28  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.12
 *
 * Revision 1.12  2004/05/25 17:08:50  dicuccio
 * Added CreateMessage() API to generate a new plugin message for a given plugin
 * call
 *
 * Revision 1.11  2004/02/12 23:03:02  mjohnson
 * Added documentation lookup.
 *
 * Revision 1.10  2004/02/03 21:23:48  dicuccio
 * Added standard accessors for the working set of plugin args
 *
 * Revision 1.9  2004/01/15 22:50:17  jcherry
 * Added FinalizeArgs() for plugins
 *
 * Revision 1.8  2003/11/06 20:04:07  dicuccio
 * Refactored FillDefaults().  Added option to have cached set of arguments
 *
 * Revision 1.7  2003/11/04 17:18:41  dicuccio
 * Changed calling API for plugins - take CPluginMessage directly instead of
 * paired command/reply
 *
 * Revision 1.6  2003/10/23 16:16:36  dicuccio
 * Exposed CPluginLibInfo
 *
 * Revision 1.5  2003/08/05 17:07:15  dicuccio
 * Changed calling semantics for the message queue - pass by reference, not
 * CConstRef<>
 *
 * Revision 1.4  2003/08/02 12:51:07  dicuccio
 * Enabled the context dictionary inside of plugin handles
 *
 * Revision 1.3  2003/07/14 13:32:13  shomrat
 * Removed unnecessary explicit class specification
 *
 * Revision 1.2  2003/07/14 11:01:02  shomrat
 * Plugin messageing system related changes
 *
 * Revision 1.1  2003/06/25 17:02:54  dicuccio
 * Split CPluginHandle into a handle (pointer-to-implementation) and
 * implementation file.  Lots of #include file clean-ups.
 *
 * ===========================================================================
 */

#endif  // GUI_CORE___PLUGIN_HANDLE_IMPL__HPP