GL Studio C++ Runtime API
dynamic_library.h
Go to the documentation of this file.
1/// \file dynamic_library.h
2/// \brief A cross-platform class for loading dynamic link libraries and shared objects.
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 INCLUDED_DISTI_DYNAMIC_LIBRARY_H
40#define INCLUDED_DISTI_DYNAMIC_LIBRARY_H
41
42#include "disti_include.h"
43
44#include <string>
45
46#if defined( _WIN32 )
47# include <windows.h>
48#endif
49
50namespace disti
51{
52typedef void* ( *FunctionPointer )( ... ); ///< Typedef for a function pointer taking variadic arguments.
53
54/// The DynamicLibrary class. A cross-platform class for loading dynamic link libraries and shared objects.
56{
57public:
58 /** Error Enum */
59 typedef enum
60 {
61 ERROR_NONE,
62 ERROR_VERSION_MISMATCH, ///< Load failed due to incompatible GL Studio or compiler versions
63 ERROR_UNKNOWN ///< Load failed for unknown reason (see DynamicLibrary::ErrorString())
65
66#if defined( _WIN32 )
67 typedef HMODULE LibHandle_t; ///< Windows uses a handle to the opened dynamic library.
68#else
69 typedef void* LibHandle_t; ///< Linux, macOS, and others use a pointer to the opened dynamic library.
70#endif
71
72 /// Constructor for dynamic library object. Causes the dynamic library which is passed in by filename to be opened.
73 /// \param lib_name_arg A pointer to a string which is a library name to be opened, may include the path, can not be NULL
74 /// \param quiet Whether this class emits error messages or fails silently.
75 /// \param searchLibPath Deprecated, unused.
76 /// \param tryStandardExtensions If this is true, the file extension, if any, will be stripped off and the appropriate
77 /// standard extension for the current OS will be appended. If the changed filename cannot be
78 /// found, then the original filename will be used as a last resort.
79 /// \param matchVersion Only load the library if it contains symbols that identify it as a GL Studio RSO, and its version information exactly matches this runtime library.
80 DISTI_EXPORT DynamicLibrary( const char* lib_name_arg, bool quiet = false, bool searchLibPath = false, bool tryStandardExtensions = false, bool matchVersion = false );
81
82 /// Destructor for dynamic library object. Closes the library so the OS can cleanup.
83 virtual DISTI_EXPORT ~DynamicLibrary();
84
85 /// Dynamically resolves a function from the library. The name of the
86 /// function is passed in.
87 /// \param function_name A pointer to a string, which represents the Name of a Function to find.
88 /// \return Returns a pointer to the function if it is found or NULL otherwise
89 virtual DISTI_EXPORT FunctionPointer DynamicFunction( const char* function_name );
90
91 /// \param libName The name of the library to load.
92 /// \param tryStandardExtensions If true, will try the standard extensions (i.e. .dll, .so, .dylib).
93 /// \return True if the library can be found somewhere on the system, false otherwise.
94 static DISTI_EXPORT bool Exists( const char* libName, bool tryStandardExtensions = true );
95
96 /// \param name The name of the file to locate.
97 /// \return The full path to the given file name.
98 static DISTI_EXPORT std::string Find( const std::string& name );
99
100 /// \return True if the library successfully loaded, false otherwise.
101 virtual DISTI_EXPORT bool Loaded() const;
102
103 /// Call LastError() when Loaded() is false to determine to determine
104 /// if load failure occured due to a version mismatch.
105 /// \return The error type, or ERROR_NONE if no failure.
106 DISTI_EXPORT ErrorEnum LastError() const;
107
108 /// \return The last error string or NULL if no error has occurred.
109 /// \note When tryStandardExtensions == true, this may be very long since it contains the error information for each attempted filename.
110 DISTI_EXPORT const char* ErrorString() const;
111
112 /// Removes the extension, if any, from the specified path.
113 /// \param libpath The path to be stripped of extensions.
114 static DISTI_EXPORT void RemoveExtension( std::string& libpath );
115
116private:
117 bool _quiet;
118 bool _tryStandardExtensions;
119 LibHandle_t _dlHandle;
120 ErrorEnum _lastError;
121
122 char* _errorString;
123
124 DISTI_EXPORT void SetErrorString( const char* );
125
126 /// Attempts to find the specified library file on the system.
127 /// If the file doesn't exist as named, any path will be stripped off and
128 /// this will try to open the library file, which uses the standard OS search
129 /// algorithm to find the file. If the open is successful, the file was
130 /// found.
131 /// \return true if the library is found.
132 static bool FoundOnSystem( const std::string& libname );
133
134 /// Opens the specified library searching the library paths if specified.
135 static LibHandle_t Open( const std::string& libpath, ErrorEnum& errorCode /*returned*/, bool searchLibPath = true, bool matchVersion = false, bool quiet = false );
136};
137
138} // namespace disti
139
140#endif
The DynamicLibrary class. A cross-platform class for loading dynamic link libraries and shared object...
Definition: dynamic_library.h:56
virtual bool Loaded() const
const char * ErrorString() const
static void RemoveExtension(std::string &libpath)
DynamicLibrary(const char *lib_name_arg, bool quiet=false, bool searchLibPath=false, bool tryStandardExtensions=false, bool matchVersion=false)
void * LibHandle_t
Linux, macOS, and others use a pointer to the opened dynamic library.
Definition: dynamic_library.h:69
ErrorEnum
Definition: dynamic_library.h:60
@ ERROR_UNKNOWN
Load failed for unknown reason (see DynamicLibrary::ErrorString())
Definition: dynamic_library.h:63
@ ERROR_VERSION_MISMATCH
Load failed due to incompatible GL Studio or compiler versions.
Definition: dynamic_library.h:62
virtual ~DynamicLibrary()
Destructor for dynamic library object. Closes the library so the OS can cleanup.
static bool Exists(const char *libName, bool tryStandardExtensions=true)
virtual FunctionPointer DynamicFunction(const char *function_name)
ErrorEnum LastError() const
static std::string Find(const std::string &name)
A file for all GL Studio files to include.
Definition: bmpimage.h:46
void *(* FunctionPointer)(...)
Typedef for a function pointer taking variadic arguments.
Definition: dynamic_library.h:52