| GL Studio C++ Runtime API

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