/*
    Copyright (C) 2008 Andreas Baumann <abaumann@yahoo.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef WOLF_LOADER_H
#define WOLF_LOADER_H

/**
 * @addtogroup wolf_library Loadable library support
 * @{
 */

/**
 * @file loader.h
 * @brief Portable library loading functions
 * @author Andreas Baumann <abaumann@yahoo.com>
 */

#ifdef __cplusplus
extern "C" {
#endif

#include "port/sys.h"

#include "errors.h"
#include <stddef.h>         /* for size_t */

#if defined _WIN32
#define WIN32_MEAN_AND_LEAN
#include <windows.h>
#endif

/* @brief handle representing a shared library
 */
typedef struct wolf_library_t *wolf_library_p;

/* @brief returned by wolf_library_get_func, cast it to the custom function pointer */
#ifdef _WIN32
#define WOLF_LIBRARY_FUNCPTR FARPROC
#else
#define WOLF_LIBRARY_FUNCPTR void *
#endif

/**
 * This macro casts a library symbol to a function pointer of a given type.
 *
 * Reason: conversion from void * to function pointer is illegal by ISO-99
 *         (though it works actually on Posix)
 *
 * for the reasons why naive casting doesn't work with dlsym, see:
 *
 * http://en.wikipedia.org/wiki/Dynamic_loading
 */
#if defined _WIN32
#define WOLF_LIBRARY_FUNC_CAST( symbol__, func_t__, func__ ) func__ = (func_t__)symbol__
#else
#define WOLF_LIBRARY_FUNC_CAST( symbol__, func_t__, func__ ) \
	{ \
		union { func_t__ f__; void *s__; } alias__; \
		alias__.s__ = symbol__; \
		func__ = alias__.f__; \
	}
#endif

/**
 * Loads a shared library.
 *
 * @param name      the name of the library to load
 * @param error     indicates errors while loading the library
 *
 * @return          the libary object
 */
wolf_library_p wolf_library_load( const char *name, wolf_error_t *error );

/**
 * Free up resources used by the library object.
 *
 * @param library   the library object to free
 *
 * @return          WOLF_OK if library has been unloaded,
 *                  WOLF_ERR_INTERNAL_STATE if the library handle is in an illegal state
 *                  (like double freeing the same library)
 */
wolf_error_t wolf_library_unload( wolf_library_p library );

/**
 * Converts the last error and state of the library object in a human readable message.
 *
 * @param library   the library object for which we want a error message
 * @param buf       the buffer which will hold the error message
 * @param buflen    the size of the buffer
 *
 * @return          a pointer to buf for convenience
 */
char *wolf_library_error_msg( const wolf_library_p library, char *buf, size_t buflen );

/**
 * Gets a symbol from the library object. It has either to be properly
 * cast to the variable to use or has to be cast to the function you are
 * expecting to call by using
 * WOLF_LIBRARY_FUNC_CAST( symbol, func_t, func ).
 *
 * @param library   the library object
 * @param name      name of the symbol to retrieve
 * @param error     WOLF_OK if the symbol could be loaded
 *
 * @return          a pointer to the retrieved symbol
 */
WOLF_LIBRARY_FUNCPTR wolf_library_get( const wolf_library_p library, const char *name, wolf_error_t *error );

/** @} */ /* @addtogroup wolf_library */

#endif /* ifndef WOLF_LOADER_H */