GL Studio C++ Runtime API
live_component_lib_ref.h
Go to the documentation of this file.
1/// \file live_component_lib_ref.h
2/// \brief The disti::LiveComponentLibRef class declaration.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<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#ifndef DISTI_INCLUDED_LIVE_COMPONENT_LIB_REF_H
40#define DISTI_INCLUDED_LIVE_COMPONENT_LIB_REF_H
41
42#include "gls_include.h"
43#include "gls_version.h"
44#include <string>
45
46namespace disti
47{
48class DynamicLibrary;
49class ComponentBase;
50#ifdef GLES
51class RSOInterfaceES1;
52typedef RSOInterfaceES1 RsoImplBaseInterface; ///< Typedef for the original RSO interface.
53#else
54class RSOInterface1;
55typedef RSOInterface1 RsoImplBaseInterface; ///< Typedef for the original RSO interface.
56#endif
57
58class GlsRSOWrapper;
59
60/** This class is used to load a live component DLL (or .so) and allow
61 * easy calling of the live component library functions through the class methods.
62 * The library remains loaded until the reference is changed to another file
63 * or object destruction.
64 */
66{
67public:
68 /// Constructs a LiveComponentLibRef.
69 /// \return A pointer to a new LiveComponentLibRef object.
71
72 /// Constructs a LiveComponentLibRef.
73 /// \param filePath If a file path is specified, it will attempt a load immediatly.
74 /// \return A pointer to a new LiveComponentLibRef object.
75 static GLS_EXPORT LiveComponentLibRef* CreateInstance( const char* filePath = NULL );
76
77 /// \return A pointer to a new clone of this object.
79
80 /** Delete a LiveComponentLibRef instance using the
81 * correct delete operator.
82 */
83 virtual GLS_EXPORT void DeleteInstance();
84
85 /// Assignment operator
86 /// \return The resulting object (this).
88
89 /// Sets the desired file name (.DLL, .so, or .dylib).
90 /// Set to NULL to unload the current library.
91 /// \param fileName The name of the library to load.
92 /// \param searchLibraryPath Unused, kept for backward compatibility.
93 GLS_EXPORT void LoadLibrary( const char* fileName, const bool searchLibraryPath = false );
94
95 /// Unloads the file.
96 void UnloadLibrary() { LoadLibrary( NULL ); }
97
98 /// \return True if the library was sucessfully loaded.
99 GLS_EXPORT bool Loaded() const;
100
101 /// \return The last error string or NULL if no error has occured.
102 GLS_EXPORT const char* ErrorString() const;
103
104 /// \return The path to the library or NULL if no library is loaded.
105 GLS_EXPORT const char* LoadedFilePath() const;
106
107 /** Returns the built version info for the given class.
108 * \param className The name of the class to check.
109 * \returns If Loaded() is true and the className is valid, returns the compiler version associated with the given class.
110 * Otherwise, the return value is undefined. */
111 GLS_EXPORT const GlsBuiltVersionInfo& BuiltVersionInfo( const char* className ) const;
112
113 /** \returns The DefaultClassName for the current LiveComponent Library if it is provided
114 * or NULL if it is unavailable. */
115 GLS_EXPORT const char* DefaultClassName() const;
116
117 /** Attempts to create a LiveComponent instance of the given class.
118 * Call Destroy() on the object to delete it safely.
119 * Objects returned by this method may not be safe to use if the GlsBuiltVersionInfo
120 * for the LiveComponent Library does not match that of the container.
121 * \param className The name of the class to instanciate.
122 * \returns Pointer to the new instance if successful, NULL otherwise. */
123 GLS_EXPORT ComponentBase* CreateLiveComponent( const char* className ) const;
124
125 /** Safely delete an object that was returned from
126 * CreateLiveComponent.
127 * \param className Must be the same name that was passed to CreateLiveComponent
128 * \param comp The component to delete */
129 GLS_EXPORT void DeleteLiveComponent( const char* className, ComponentBase* comp ) const;
130
131 /** Attempts to create a LiveComponent instance of the given class using the safe interface.
132 * Call DestroyInstance() on the object to delete it safely.
133 * \param className The name of the class to instanciate.
134 * \param[out] RSOVersion The version number of the RSO and the returned interface
135 * \returns Pointer to the new instance if successful, NULL otherwise. */
136 GLS_EXPORT RsoImplBaseInterface* CreateRSOInterface( const char* className, unsigned int& RSOVersion ) const;
137
138protected:
139 /** Constructs a LiveComponentLibRef.
140 * Private - call CreateInstance instead
141 * \param filePath If a file path is specified, it will attempt a load immediatly.
142 */
143 LiveComponentLibRef( const char* filePath = NULL );
144
145 /// Copy constructor
147
148 /** Destructor
149 * Private - call DeleteInstance instead.
150 */
152
153 std::string _loadedFilePath; ///< The path to the file that is currently loaded.
154 DynamicLibrary* _lib; ///< Pointer to the underlying library reference.
155 char* _errorString; ///< String of the last error encountered.
156
157 /// Unused, kept for backward compatibility.
159
160 /// Unused, kept for backward compatibility.
161 /// \return Not implemented.
163
164 /// Set the underlying error string signifying the last error encountered.
165 /// \param value The new error string to set.
166 GLS_EXPORT void SetErrorString( const char* value );
167
168 /// Allow or disallow version compatibility popups.
169 /// \param className The generated class name.
170 /// \param value The new dialog enabled flag.
171 void EnableDialogs( const char* className, bool value ) const;
172};
173
174} // namespace disti
175
176#endif
Definition: component_base.h:67
The DynamicLibrary class. A cross-platform class for loading dynamic link libraries and shared object...
Definition: dynamic_library.h:56
Definition: gls_version.h:223
Definition: gls_rso_wrapper.h:65
Definition: live_component_lib_ref.h:66
DynamicLibrary * _lib
Pointer to the underlying library reference.
Definition: live_component_lib_ref.h:154
const char * ErrorString() const
ComponentBase * CreateLiveComponent(const char *className) const
const char * LoadedFilePath() const
void EnableDialogs(const char *className, bool value) const
static LiveComponentLibRef * CreateInstance(const LiveComponentLibRef &)
virtual void DeleteInstance()
LiveComponentLibRef(const LiveComponentLibRef &)
Copy constructor.
virtual LiveComponentLibRef * CloneObject() const
LiveComponentLibRef(const char *filePath=NULL)
char * _errorString
String of the last error encountered.
Definition: live_component_lib_ref.h:155
void DeleteLibrary()
Unused, kept for backward compatibility.
std::string _loadedFilePath
The path to the file that is currently loaded.
Definition: live_component_lib_ref.h:153
const LiveComponentLibRef & operator=(const LiveComponentLibRef &)
const char * DefaultClassName() const
void UnloadLibrary()
Unloads the file.
Definition: live_component_lib_ref.h:96
static LiveComponentLibRef * CreateInstance(const char *filePath=NULL)
RsoImplBaseInterface * CreateRSOInterface(const char *className, unsigned int &RSOVersion) const
void DeleteLiveComponent(const char *className, ComponentBase *comp) const
void SetErrorString(const char *value)
void LoadLibrary(const char *fileName, const bool searchLibraryPath=false)
const GlsBuiltVersionInfo & BuiltVersionInfo(const char *className) const
Definition: rso_interface_1.h:60
A file for all GL Studio files to include.
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
Used for matching version of libraries and headers.
Definition: bmpimage.h:46
RSOInterface1 RsoImplBaseInterface
Typedef for the original RSO interface.
Definition: live_component_lib_ref.h:55