dynamic_library.h

Go to the documentation of this file.

/*! \file
  \brief  A cross-platform class for loading dynamic link libraries and shared objects.
 
  \par Copyright Information
 
  Copyright (c) 2017 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 _DYNAMIC_LIBRARY_H
#define _DYNAMIC_LIBRARY_H
 
#include "disti_include.h"
 
#include <string>
 
#if defined( _WIN32 )
#    include <windows.h>
#endif
 
namespace disti
{
typedef void* ( *FunctionPointer )( ... ); ///< Typedef for a function pointer taking variadic arguments.
 
/// The DynamicLibrary class. A cross-platform class for loading dynamic link libraries and shared objects.
class DynamicLibrary
{
public:
    /** Error Enum */
    typedef enum
    {
        ERROR_NONE,
        ERROR_VERSION_MISMATCH, ///< Load failed due to incompatible GL Studio or compiler versions
        ERROR_UNKNOWN           ///< Load failed for unknown reason (see DynamicLibrary::ErrorString())
    } ErrorEnum;
 
#if defined( _WIN32 )
    typedef HMODULE LibHandle_t; ///< Windows uses a handle to the opened dynamic library.
#else
    typedef void* LibHandle_t; ///< Linux, macOS, and others use a pointer to the opened dynamic library.
#endif
 
    /// Constructor for dynamic library object. Causes the dynamic library which is passed in by filename to be opened.
    /// \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
    /// \param quiet Whether this class emits error messages or fails silently.
    /// \param searchLibPath Deprecated, unused.
    /// \param tryStandardExtensions If this is true, the file extension, if any, will be stripped off and the appropriate
    ///                              standard extension for the current OS will be appended. If the changed filename cannot be
    ///                              found, then the original filename will be used as a last resort.
    /// \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.
    DISTI_EXPORT DynamicLibrary( const char* lib_name_arg, bool quiet = false, bool searchLibPath = false, bool tryStandardExtensions = false, bool matchVersion = false );
 
    /// Destructor for dynamic library object. Closes the library so the OS can cleanup.
    virtual DISTI_EXPORT ~DynamicLibrary();
 
    /// Dynamically resolves a function from the library.  The name of the
    /// function is passed in.
    /// \param function_name A pointer to a string, which represents the Name of a Function to find.
    /// \return Returns a pointer to the function if it is found or NULL otherwise
    virtual DISTI_EXPORT FunctionPointer DynamicFunction( const char* function_name );
 
    /// \param libName The name of the library to load.
    /// \param tryStandardExtensions If true, will try the standard extensions (i.e. .dll, .so, .dylib).
    /// \return True if the library can be found somewhere on the system, false otherwise.
    static DISTI_EXPORT bool Exists( const char* libName, bool tryStandardExtensions = true );
 
    /// \param name The name of the file to locate.
    /// \return The full path to the given file name.
    static DISTI_EXPORT std::string Find( const std::string& name );
 
    /// \return True if the library successfully loaded, false otherwise.
    virtual DISTI_EXPORT bool Loaded() const;
 
    /// Call LastError() when Loaded() is false to determine to determine
    /// if load failure occured due to a version mismatch.
    /// \return The error type, or ERROR_NONE if no failure.
    DISTI_EXPORT ErrorEnum LastError() const;
 
    /// \return The last error string or NULL if no error has occurred.
    /// \note When tryStandardExtensions == true, this may be very long since it contains the error information for each attempted filename.
    DISTI_EXPORT const char* ErrorString() const;
 
    /// Removes the extension, if any, from the specified path.
    /// \param libpath The path to be stripped of extensions.
    static DISTI_EXPORT void RemoveExtension( std::string& libpath );
 
private:
    bool        _quiet;
    bool        _tryStandardExtensions;
    LibHandle_t _dlHandle;
    ErrorEnum   _lastError;
 
    char* _errorString;
 
    DISTI_EXPORT void SetErrorString( const char* );
 
    /// Attempts to find the specified library file on the system.
    /// If the file doesn't exist as named, any path will be stripped off and
    /// this will try to open the library file, which uses the standard OS search
    /// algorithm to find the file.  If the open is successful, the file was
    /// found.
    /// \return true if the library is found.
    static bool FoundOnSystem( const std::string& libname );
 
    /// Opens the specified library searching the library paths if specified.
    static LibHandle_t Open( const std::string& libpath, ErrorEnum& errorCode /*returned*/, bool searchLibPath = true, bool matchVersion = false, bool quiet = false );
};
 
} // namespace disti
 
#endif