| GL Studio C++ Runtime API

live_component_lib_ref.h
Go to the documentation of this file.
1/*! \file
2 \brief The disti::LiveComponentLibRef class declaration.
3
4 \par Copyright Information
5
6 Copyright (c) 2017 by The DiSTI Corporation.<br>
7 11301 Corporate Blvd; Suite 100<br>
8 Orlando, Florida 32817<br>
9 USA<br>
10 <br>
11 All rights reserved.<br>
12
13 This Software contains proprietary trade secrets of DiSTI and may not be
14 reproduced, in whole or part, in any form, or by any means of electronic,
15 mechanical, or otherwise, without the written permission of DiSTI. Said
16 permission may be derived through the purchase of applicable DiSTI product
17 licenses which detail the distribution rights of this content and any
18 Derivative Works based on this or other copyrighted DiSTI Software.
19
20 NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21 AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22 PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23 AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24 IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25 PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26
27 LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28 IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29 INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30 DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31 INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32 INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33 OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34 EXCEED FIVE DOLLARS (US$5.00).
35
36 The aforementioned terms and restrictions are governed by the laws of the
37 State of Florida and the United States of America.
38
39*/
40#ifndef _LIVE_COMPONENT_LIB_REF_H
41#define _LIVE_COMPONENT_LIB_REF_H
42
43#include "gls_include.h"
44#include "gls_version.h"
45#include <string>
46
47 namespace disti
48{
49 class DynamicLibrary;
50 class ComponentBase;
51#ifdef GLES
52 class RSOInterfaceES1;
53 typedef RSOInterfaceES1 RsoImplBaseInterface; ///< Typedef for the original RSO interface.
54#else
55 class RSOInterface1;
56 typedef RSOInterface1 RsoImplBaseInterface; ///< Typedef for the original RSO interface.
57#endif
58
59 class GlsRSOWrapper;
60
61/** This class is used to load a live component DLL (or .so) and allow
62 * easy calling of the live component library functions through the class methods.
63 * The library remains loaded until the reference is changed to another file
64 * or object destruction.
65 */
66 class LiveComponentLibRef
67{
68 public:
69 /// Constructs a LiveComponentLibRef.
70 /// \return A pointer to a new LiveComponentLibRef object.
71 static GLS_EXPORT LiveComponentLibRef* CreateInstance( const LiveComponentLibRef& );
72
73 /// Constructs a LiveComponentLibRef.
74 /// \param filePath If a file path is specified, it will attempt a load immediatly.
75 /// \return A pointer to a new LiveComponentLibRef object.
76 static GLS_EXPORT LiveComponentLibRef* CreateInstance( const char* filePath = NULL );
77
78 /// \return A pointer to a new clone of this object.
79 virtual GLS_EXPORT LiveComponentLibRef* CloneObject() const;
80
81 /** Delete a LiveComponentLibRef instance using the
82 * correct delete operator.
83 */
84 virtual GLS_EXPORT void DeleteInstance();
85
86 /// Assignment operator
87 /// \return The resulting object (this).
88 GLS_EXPORT const LiveComponentLibRef& operator=( const LiveComponentLibRef& );
89
90 /// Sets the desired file name (.DLL, .so, or .dylib).
91 /// Set to NULL to unload the current library.
92 /// \param fileName The name of the library to load.
93 /// \param searchLibraryPath Unused, kept for backward compatibility.
94 GLS_EXPORT void LoadLibrary( const char* fileName, const bool searchLibraryPath = false );
95
96 /// Unloads the file.
97 inline void UnloadLibrary() { LoadLibrary( NULL ); }
98
99 /// \return True if the library was sucessfully loaded.
100 GLS_EXPORT bool Loaded() const;
101
102 /// \return The last error string or NULL if no error has occured.
103 GLS_EXPORT const char* ErrorString() const;
104
105 /// \return The path to the library or NULL if no library is loaded.
106 GLS_EXPORT const char* LoadedFilePath() const;
107
108 /** Returns the built version info for the given class.
109 * \param className The name of the class to check.
110 * \returns If Loaded() is true and the className is valid, returns the compiler version associated with the given class.
111 * Otherwise, the return value is undefined. */
112 GLS_EXPORT const GlsBuiltVersionInfo& BuiltVersionInfo( const char* className ) const;
113
114 /** \returns The DefaultClassName for the current LiveComponent Library if it is provided
115 * or NULL if it is unavailable. */
116 GLS_EXPORT const char* DefaultClassName() const;
117
118 /** Attempts to create a LiveComponent instance of the given class.
119 * Call Destroy() on the object to delete it safely.
120 * Objects returned by this method may not be safe to use if the GlsBuiltVersionInfo
121 * for the LiveComponent Library does not match that of the container.
122 * \param className The name of the class to instanciate.
123 * \returns Pointer to the new instance if successful, NULL otherwise. */
124 GLS_EXPORT ComponentBase* CreateLiveComponent( const char* className ) const;
125
126 /** Safely delete an object that was returned from
127 * CreateLiveComponent.
128 * \param className Must be the same name that was passed to CreateLiveComponent
129 * \param comp The component to delete */
130 GLS_EXPORT void DeleteLiveComponent( const char* className, ComponentBase* comp ) const;
131
132 /** Attempts to create a LiveComponent instance of the given class using the safe interface.
133 * Call DestroyInstance() on the object to delete it safely.
134 * \param className The name of the class to instanciate.
135 * \param[out] RSOVersion The version number of the RSO and the returned interface
136 * \returns Pointer to the new instance if successful, NULL otherwise. */
137 GLS_EXPORT RsoImplBaseInterface* CreateRSOInterface( const char* className, unsigned int& RSOVersion ) const;
138
139 protected:
140 /** Constructs a LiveComponentLibRef.
141 * Private - call CreateInstance instead
142 * \param filePath If a file path is specified, it will attempt a load immediatly.
143 */
144 LiveComponentLibRef( const char* filePath = NULL );
145
146 /// Copy constructor
147 LiveComponentLibRef( const LiveComponentLibRef& );
148
149 /** Destructor
150 * Private - call DeleteInstance instead.
151 */
152 virtual GLS_EXPORT ~LiveComponentLibRef();
153
154 std::string _loadedFilePath; ///< The path to the file that is currently loaded.
155 DynamicLibrary* _lib; ///< Pointer to the underlying library reference.
156 char* _errorString; ///< String of the last error encountered.
157
158 /// Unused, kept for backward compatibility.
159 GLS_EXPORT void DeleteLibrary();
160
161 /// Unused, kept for backward compatibility.
162 /// \return Not implemented.
163 GLS_EXPORT bool UpdateLoad();
164
165 /// Set the underlying error string signifying the last error encountered.
166 /// \param value The new error string to set.
167 GLS_EXPORT void SetErrorString( const char* value );
168
169 /// Allow or disallow version compatibility popups.
170 /// \param className The generated class name.
171 /// \param value The new dialog enabled flag.
172 void EnableDialogs( const char* className, bool value ) const;
173};
174
175} // namespace disti
176
177#endif
disti::ComponentBase
Definition: component_base.h:68
disti::DynamicLibrary
The DynamicLibrary class. A cross-platform class for loading dynamic link libraries and shared object...
Definition: dynamic_library.h:57
disti::GlsBuiltVersionInfo2
Definition: gls_version.h:234
disti::GlsRSOWrapper
Definition: gls_rso_wrapper.h:66
disti::LiveComponentLibRef
Definition: live_component_lib_ref.h:67
disti::LiveComponentLibRef::_lib
DynamicLibrary * _lib
Pointer to the underlying library reference.
Definition: live_component_lib_ref.h:155
disti::LiveComponentLibRef::ErrorString
const char * ErrorString() const
disti::LiveComponentLibRef::CreateLiveComponent
ComponentBase * CreateLiveComponent(const char *className) const
disti::LiveComponentLibRef::~LiveComponentLibRef
virtual ~LiveComponentLibRef()
disti::LiveComponentLibRef::LoadedFilePath
const char * LoadedFilePath() const
disti::LiveComponentLibRef::EnableDialogs
void EnableDialogs(const char *className, bool value) const
disti::LiveComponentLibRef::CreateInstance
static LiveComponentLibRef * CreateInstance(const LiveComponentLibRef &)
disti::LiveComponentLibRef::DeleteInstance
virtual void DeleteInstance()
disti::LiveComponentLibRef::Loaded
bool Loaded() const
disti::LiveComponentLibRef::LiveComponentLibRef
LiveComponentLibRef(const LiveComponentLibRef &)
Copy constructor.
disti::LiveComponentLibRef::CloneObject
virtual LiveComponentLibRef * CloneObject() const
disti::LiveComponentLibRef::LiveComponentLibRef
LiveComponentLibRef(const char *filePath=NULL)
disti::LiveComponentLibRef::_errorString
char * _errorString
String of the last error encountered.
Definition: live_component_lib_ref.h:156
disti::LiveComponentLibRef::DeleteLibrary
void DeleteLibrary()
Unused, kept for backward compatibility.
disti::LiveComponentLibRef::UpdateLoad
bool UpdateLoad()
disti::LiveComponentLibRef::_loadedFilePath
std::string _loadedFilePath
The path to the file that is currently loaded.
Definition: live_component_lib_ref.h:154
disti::LiveComponentLibRef::operator=
const LiveComponentLibRef & operator=(const LiveComponentLibRef &)
disti::LiveComponentLibRef::DefaultClassName
const char * DefaultClassName() const
disti::LiveComponentLibRef::UnloadLibrary
void UnloadLibrary()
Unloads the file.
Definition: live_component_lib_ref.h:97
disti::LiveComponentLibRef::CreateInstance
static LiveComponentLibRef * CreateInstance(const char *filePath=NULL)
disti::LiveComponentLibRef::CreateRSOInterface
RsoImplBaseInterface * CreateRSOInterface(const char *className, unsigned int &RSOVersion) const
disti::LiveComponentLibRef::DeleteLiveComponent
void DeleteLiveComponent(const char *className, ComponentBase *comp) const
disti::LiveComponentLibRef::SetErrorString
void SetErrorString(const char *value)
disti::LiveComponentLibRef::LoadLibrary
void LoadLibrary(const char *fileName, const bool searchLibraryPath=false)
disti::LiveComponentLibRef::BuiltVersionInfo
const GlsBuiltVersionInfo & BuiltVersionInfo(const char *className) const
disti::RSOInterface1
Definition: rso_interface_1.h:61
gls_include.h
A file for all GL Studio files to include.
GLS_EXPORT
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:52
gls_version.h
Used for matching version of libraries and headers.
disti
Definition: bmpimage.h:47
disti::RsoImplBaseInterface
RSOInterfaceES1 RsoImplBaseInterface
Typedef for the original RSO interface.
Definition: live_component_lib_ref.h:53