live_component_lib_ref.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::LiveComponentLibRef class declaration.

  \par Copyright Information

  Copyright (c) 2015 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 "version.h"
#include <string>

namespace disti {

class DynamicLibrary;
class ComponentBase;
class RSOInterface1;
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. */
    static GLS_EXPORT LiveComponentLibRef* CreateInstance(const LiveComponentLibRef&);
    /** Constructs a LiveComponentLibRef.  
      * \param filePath If a file path is specified, it will attempt a load immediatly.
      */
    static GLS_EXPORT LiveComponentLibRef* CreateInstance(const char* filePath = NULL);

    virtual GLS_EXPORT LiveComponentLibRef* CloneObject() const;

    /** Delete a LiveComponentLibRef instance using the
      * correct delete operator.
      */
    virtual GLS_EXPORT void DeleteInstance();

    GLS_EXPORT const LiveComponentLibRef& operator=(const LiveComponentLibRef&);

    /** Sets the desired file name (.DLL or .so).
      * Set to NULL to unload the current library. */
    GLS_EXPORT void LoadLibrary(const char* fileName, const bool searchLibraryPath = false);
    inline void UnloadLibrary() { LoadLibrary(NULL); }

    /** Returns true if the library was sucessfully loaded. */
    GLS_EXPORT bool Loaded() const;

    /** Returns the last error string or NULL if no error has occured. */
    GLS_EXPORT  const char* ErrorString() const;

    /** Returns 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
      * \param hidePopups When enabled, tells the GL Studio runtime to hide popups for "missing license","missing texture", etc.
      *        \note: if you hide the popups the RSO may just kill the application when it needs a license.
      * \returns Pointer to the new instance if successful, NULL otherwise. */
    GLS_EXPORT RSOInterface1* CreateRSOInterface(const char* className, unsigned int &RSOVersion, bool hidePopups=false) 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);
    LiveComponentLibRef(const LiveComponentLibRef&);
    /** Destructor
      * Private - call DeleteInstance instead.
      */
    virtual GLS_EXPORT ~LiveComponentLibRef();

    std::string _loadedFilePath;
    DynamicLibrary* _lib;
    char* _errorString;

    GLS_EXPORT void DeleteLibrary();

    GLS_EXPORT bool UpdateLoad();
    
    GLS_EXPORT void SetErrorString(const char* value);
};

} // namespace disti

#endif