DDD_DynamicLibrary.h

Go to the documentation of this file.

#ifndef _DDD_DYNAMIC_LIBRARY_H
#define _DDD_DYNAMIC_LIBRARY_H

/*! \file DDD_DynamicLibrary.h
  \brief  A cross-platform class for loading dynamic link libraries and shared objects

  \par Copyright Information

  Copyright (c) 2012 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 POSSIBLITY
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.

*/

#include <string>
#include "DDD_Include.h"
#include "DDD_LogFacade.h"

#if defined(_WIN32)
#   include <windows.h>
#endif

namespace disti
{

typedef void * (*FunctionPointer)(...);



/** \brief The DynamicLibrary class. A cross-platform class for loading dynamic link libraries 
           and shared objects
  * \note   This class is very similar to GL Studio's "DynamicLibrary" class. It has been moved here to remove the 
            DataDirector's GLStudio runtime DLL dependency. It has also been tweaked and renamed to avoid
            collisions with libraries that load both Data Director and GL Studio runtime DLLs and modified to use
            the DDD_Logger for error reporting
*/
class DDD_DynamicLibraryPlugin : public DDD_LogFacade
{
public:
    /** The default extension for this library */
    static const std::string LIB_EXT_STRING;

    typedef enum 
    {
        ERROR_NONE, 
        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 A pointer to a string which is a library name to be opened, may include the path, can not be NULL

    */
    DDD_EXPORT DDD_DynamicLibraryPlugin(const char* lib_name_arg);

    /** Destructor for dynamic library object.  Closes the library so the OS can cleanup. */
    virtual DDD_EXPORT ~DDD_DynamicLibraryPlugin();

    /** 
    * 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 DDD_EXPORT FunctionPointer DynamicFunction(const char *function_name);

    /** \return True if the library can be found somewhere on the system, false otherwise */
    static DDD_EXPORT bool Exists(const char* libName);

    static DDD_EXPORT std::string Find(const std::string& name);

    /** \return True if the library successfully loaded, false otherwise */
    virtual DDD_EXPORT bool Loaded(void) const;

    /** Call LastError() when Loaded() is false to determine to determine
      * if load failure occured due to a version mismatch.
      */
    DDD_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.
      */
    DDD_EXPORT const char* ErrorString() const;

    /**
    * Removes the extension, if any, from the specified path
    */
    static DDD_EXPORT void RemoveExtension(std::string& libpath);

private:

    LibHandle_t _dlHandle;
    ErrorEnum _lastError; 
    
    char* _errorString;

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

};

} // namespace disti

#endif