plugin_handle.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: plugin_handle.hpp,v $
 * PRODUCTION Revision 1000.5  2004/06/01 19:46:58  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.19
 * PRODUCTION
 * ===========================================================================
 */

#ifndef GUI_CORE___PLUGIN_HANDLE__HPP
#define GUI_CORE___PLUGIN_HANDLE__HPP

/*  $Id: plugin_handle.hpp,v 1000.5 2004/06/01 19:46:58 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:
 *    CPluginHandle -- application-side wrapper for a CPluginFactoryBase that
 *                     supports delayed instantiation of a plugin
 */


#include <corelib/ncbiobj.hpp>
#include <gui/plugin/AlgoCommand.hpp>
#include <gui/plugin/DataCommand.hpp>
#include <gui/plugin/ViewCommand.hpp>
#include <gui/plugin/PluginCommandSet.hpp>


BEGIN_NCBI_SCOPE

// predeclarations to avoid some includes and dependencies
// we include predeclarations in ncbi::objects::

BEGIN_SCOPE(objects)
    class CPluginRequest;
    class CPluginReply;
    class CPluginMessage;
    class CPluginInfo;
    class CPluginLibInfo;
END_SCOPE(objects)

class CPluginHandle_Impl;

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

    // default ctor
    CPluginHandle();

    CPluginHandle(const CPluginHandle& handle);
    CPluginHandle& operator=(const CPluginHandle& handle);
    ~CPluginHandle();

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

    // determine if a given command sub-type is supported by this plugin
    bool HasCommandSubtype(objects::EAlgoCommand) const;
    bool HasCommandSubtype(objects::EDataCommand) const;
    bool HasCommandSubtype(objects::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 command
    bool FillDefaults(objects::EAlgoCommand cmd,
                      objects::CPluginCommand& args) const;

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

    // fill in a default set of arguments for the specified view command
    bool FillDefaults(objects::EViewCommand cmd,
                      objects::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 given command
    void Execute(objects::CPluginMessage& msg);

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

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

    // get the plugin libinfo
    const objects::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.
    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;

    // determine if a given plugin handle sorts to less than the current handle
    bool LessThan(const CPluginHandle& other) const;

    // operator bool() for determining validity
    operator bool(void) const;

private:
    // we maintain a pointer to our implementation
    CRef<CPluginHandle_Impl> m_Impl;

    // explicit private ctor for creating handles from implementations
    explicit CPluginHandle(CPluginHandle_Impl& impl);

    // private handler for thrown exceptions
    void x_ThrowInvalidHandle() const;
};


// comparison operators for plugin handles
NCBI_XGBPLUGIN_EXPORT
bool operator< (const CPluginHandle& h1, const CPluginHandle& h2);


NCBI_XGBPLUGIN_EXPORT
bool operator== (const CPluginHandle& h1, const CPluginHandle& h2);


NCBI_XGBPLUGIN_EXPORT
bool operator!= (const CPluginHandle& h1, const CPluginHandle& h2);


inline
CPluginHandle::operator bool(void) const
{
    return m_Impl ? true : false;
}


END_NCBI_SCOPE


#endif  // GUI_CORE___PLUGIN_HANDLE__HPP

/*
 * ===========================================================================
 * $Log: plugin_handle.hpp,v $
 * Revision 1000.5  2004/06/01 19:46:58  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.19
 *
 * Revision 1.19  2004/05/25 17:07:49  dicuccio
 * Added CreateMessage() API - creates a fully-formed plugin message for a given
 * plugin call
 *
 * Revision 1.18  2004/02/12 23:03:42  mjohnson
 * Added documentation lookup. Help buttons should all be enabled,
 * and will launch browser to wiki when pressed.
 *
 * Revision 1.17  2004/01/15 22:50:18  jcherry
 * Added FinalizeArgs() for plugins
 *
 * Revision 1.16  2003/11/26 17:04:33  dicuccio
 * Added standard function to handle all exception throwing
 *
 * Revision 1.15  2003/11/06 19:54:01  dicuccio
 * Added comments.  Removed dead APIs
 *
 * Revision 1.14  2003/11/04 17:12:08  dicuccio
 * Dropped const requirement for CPluginMessage
 *
 * Revision 1.13  2003/10/23 16:12:15  dicuccio
 * Exposed the CPluginLibInfo object behind the handle
 *
 * Revision 1.12  2003/08/22 15:54:48  dicuccio
 * General clean-up:  Removed unneeded export specifiers from templates; removed
 * 'USING_SCOPE(objects)'
 *
 * Revision 1.11  2003/08/05 16:58:39  dicuccio
 * Changed calling conventions for plugin message queue - pass by reference, not
 * CConstRef<>
 *
 * Revision 1.10  2003/07/14 10:58:05  shomrat
 * Plugin messageing system related changes
 *
 * Revision 1.9  2003/06/27 14:37:04  shomrat
 * Added comparison operators == and !=
 *
 * Revision 1.8  2003/06/25 16:59:41  dicuccio
 * Changed CPluginHandle into a pointer-to-implementation (the previous
 * implementation is now the pointer held).  Lots of #include file clean-ups.
 *
 * Revision 1.7  2003/06/20 14:44:36  dicuccio
 * Revamped handling of plugin registration.  All plugin factories now derive
 * from CPluginFactoryBase; CPluginFactory is a template.  There is a new
 * requirement for derived plugin handlers of all types (each must implement a
 * static function of the form 'static void GetInfo(CPluginInfo&)')
 *
 * Revision 1.6  2003/05/19 13:32:43  dicuccio
 * Moved gui/core/plugin --> gui/plugin/
 *
 * Revision 1.5  2003/03/25 14:20:47  dicuccio
 * Changed export specifier from XGBPLUGIN to GUICORE
 *
 * Revision 1.4  2003/02/28 15:05:13  dicuccio
 * Added a flag for querying the 'enabled' status of a plugin
 *
 * Revision 1.3  2003/02/24 13:00:17  dicuccio
 * Renamed classes in plugin spec:
 *     CArgSeg --> CPluginArgSet
 *     CArgument --> CPluginArg
 *     CPluginArgs --> CPluginCommand
 *     CPluginCommands --> CPluginCommandSet
 *
 * Revision 1.2  2003/02/21 16:44:13  dicuccio
 * Added Win32 export specifiers for new plugin library.  Fixed compilation
 * issues for Win32.
 *
 * Revision 1.1  2003/02/20 19:44:06  dicuccio
 * Created new plugin architecture, mediated via an ASN.1 spec.  Moved GBENCH
 * framework over to use new plugin architecture.
 *
 * ===========================================================================
 */