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 )( ... );

/** 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 Open Dynamic Library */
#else
    typedef void* LibHandle_t; /** UNIX uses a pointer to the Open 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 whether or not the library path is searched to find the library if it cannot be found
    *                      first in its specified directory.
    * \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
    */
    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 );

    /** \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 );

    /** \return The 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( void ) const;

    /** Call LastError() when Loaded() is false to determine to determine
      * if load failure occured due to a version mismatch.
      */
    DISTI_EXPORT ErrorEnum LastError() const;

    /** Returns the last error string or NULL if no error has occured.
      * When tryStandardExtensions == true, this may be a very long string
      * 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
    */
    static DISTI_EXPORT void RemoveExtension( std::string& libpath );

private:
    bool        _quiet;
    bool        _searchLibPath;
    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.
    *
    * \returns 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