live_component_lib_ref.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::LiveComponentLibRef class declaration.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>
 
  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.
 
  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
 
  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).
 
  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.
 
*/
#ifndef _LIVE_COMPONENT_LIB_REF_H
#define _LIVE_COMPONENT_LIB_REF_H
 
#include "gls_include.h"
#include "gls_version.h"
#include <string>
 
namespace disti
{
class DynamicLibrary;
class ComponentBase;
#ifdef GLES
class RSOInterfaceES1;
typedef RSOInterfaceES1 RsoImplBaseInterface; ///< Typedef for the original RSO interface.
#else
class RSOInterface1;
typedef RSOInterface1 RsoImplBaseInterface; ///< Typedef for the original RSO interface.
#endif
 
class GlsRSOWrapper;
 
/** This class is used to load a live component DLL (or .so) and allow
  * easy calling of the live component library functions through the class methods.
  * The library remains loaded until the reference is changed to another file
  * or object destruction.
  */
class LiveComponentLibRef
{
public:
    /// Constructs a LiveComponentLibRef.
    /// \return A pointer to a new LiveComponentLibRef object.
    static GLS_EXPORT LiveComponentLibRef* CreateInstance( const LiveComponentLibRef& );
 
    /// Constructs a LiveComponentLibRef.
    /// \param filePath If a file path is specified, it will attempt a load immediatly.
    /// \return A pointer to a new LiveComponentLibRef object.
    static GLS_EXPORT LiveComponentLibRef* CreateInstance( const char* filePath = NULL );
 
    /// \return A pointer to a new clone of this object.
    virtual GLS_EXPORT LiveComponentLibRef* CloneObject() const;
 
    /** Delete a LiveComponentLibRef instance using the
      * correct delete operator.
      */
    virtual GLS_EXPORT void DeleteInstance();
 
    /// Assignment operator
    /// \return The resulting object (this).
    GLS_EXPORT const LiveComponentLibRef& operator=( const LiveComponentLibRef& );
 
    /// Sets the desired file name (.DLL, .so, or .dylib).
    /// Set to NULL to unload the current library.
    /// \param fileName The name of the library to load.
    /// \param searchLibraryPath Unused, kept for backward compatibility.
    GLS_EXPORT void LoadLibrary( const char* fileName, const bool searchLibraryPath = false );
 
    /// Unloads the file.
    inline void UnloadLibrary() { LoadLibrary( NULL ); }
 
    /// \return True if the library was sucessfully loaded.
    GLS_EXPORT bool Loaded() const;
 
    /// \return The last error string or NULL if no error has occured.
    GLS_EXPORT const char* ErrorString() const;
 
    /// \return The path to the library or NULL if no library is loaded.
    GLS_EXPORT const char* LoadedFilePath() const;
 
    /** Returns the built version info for the given class.
      * \param className The name of the class to check.
      * \returns If Loaded() is true and the className is valid, returns the compiler version associated with the given class.
      * Otherwise, the return value is undefined. */
    GLS_EXPORT const GlsBuiltVersionInfo& BuiltVersionInfo( const char* className ) const;
 
    /** \returns The DefaultClassName for the current LiveComponent Library if it is provided
      *          or NULL if it is unavailable. */
    GLS_EXPORT const char* DefaultClassName() const;
 
    /** Attempts to create a LiveComponent instance of the given class.
      * Call Destroy() on the object to delete it safely.
      * Objects returned by this method may not be safe to use if the GlsBuiltVersionInfo
      * for the LiveComponent Library does not match that of the container.
      * \param className The name of the class to instanciate.
      * \returns Pointer to the new instance if successful, NULL otherwise. */
    GLS_EXPORT ComponentBase* CreateLiveComponent( const char* className ) const;
 
    /** Safely delete an object that was returned from
      * CreateLiveComponent.
      * \param className Must be the same name that was passed to CreateLiveComponent
      * \param comp The component to delete */
    GLS_EXPORT void DeleteLiveComponent( const char* className, ComponentBase* comp ) const;
 
    /** Attempts to create a LiveComponent instance of the given class using the safe interface.
      * Call DestroyInstance() on the object to delete it safely.
      * \param className The name of the class to instanciate.
      * \param[out] RSOVersion The version number of the RSO and the returned interface
      * \returns Pointer to the new instance if successful, NULL otherwise. */
    GLS_EXPORT RsoImplBaseInterface* CreateRSOInterface( const char* className, unsigned int& RSOVersion ) const;
 
protected:
    /** Constructs a LiveComponentLibRef.  
      * Private - call CreateInstance instead
      * \param filePath If a file path is specified, it will attempt a load immediatly.
      */
    LiveComponentLibRef( const char* filePath = NULL );
 
    /// Copy constructor
    LiveComponentLibRef( const LiveComponentLibRef& );
 
    /** Destructor
      * Private - call DeleteInstance instead.
      */
    virtual GLS_EXPORT ~LiveComponentLibRef();
 
    std::string     _loadedFilePath; ///< The path to the file that is currently loaded.
    DynamicLibrary* _lib;            ///< Pointer to the underlying library reference.
    char*           _errorString;    ///< String of the last error encountered.
 
    /// Unused, kept for backward compatibility.
    GLS_EXPORT void DeleteLibrary();
 
    /// Unused, kept for backward compatibility.
    /// \return Not implemented.
    GLS_EXPORT bool UpdateLoad();
 
    /// Set the underlying error string signifying the last error encountered.
    /// \param value The new error string to set.
    GLS_EXPORT void SetErrorString( const char* value );
 
    /// Allow or disallow version compatibility popups.
    /// \param className The generated class name.
    /// \param value The new dialog enabled flag.
    void EnableDialogs( const char* className, bool value ) const;
};
 
} // namespace disti
 
#endif