src/common/DynamicLibraries.h

/*
    Copyright (C) 2010 Christian Schoenebeck
*/

#ifndef LS_DYNAMIC_LIBRARIES_H
#define LS_DYNAMIC_LIBRARIES_H

#include "Exception.h"
#include <string>

namespace LinuxSampler {

/**
 * Function signature for callback functions used with function
 * DynamicLibrariesSearch() .
 *
 * @param filename - full qualified filename of DLL
 * @param hDLL - handle of opened DLL
 * @param pFunction - pointer to requested function of DLL
 * @param pCustom - (optional) custom data
 */
typedef void DynamicLibrariesSearchCallbackFunction(
    String filename, void* hDLL, void* pFunction, void* pCustom
);

/**
 * Search and load DLLs in the directory given by @a dir . For each DLL found,
 * the library function supplied by @a funct is tried to be loaded and on
 * success for each such DLL, the callback function @a pCallback is called.
 *
 * @e Note: This function leaves all DLLs open! You should close them once you
 * don't need them anymore by calling DynamicLibraryClose() .
 *
 * @param dir - DLL directory
 * @param funct - entry function to be loaded for each DLL
 * @param pCallback - callback function which is called for each DLL found
 * @param pCustom - (optional) arbitrary data passed to the callback function
 * @throws Exception - if supplied directory cannot be opened
 * @returns amount of DLLs loaded successfully
 */
int DynamicLibrariesSearch(String dir, String funct, DynamicLibrariesSearchCallbackFunction* pCallback, void* pCustom = NULL) throw (Exception);

/**
 * Load the DLL given by @a filename . A DLL can be opened multiple times. A
 * reference count is used in this case.
 *
 * @param filename - DLL to be loaded
 * @returns handle to opened DLL or NULL on error
 */
void* DynamicLibraryOpen(String filename);

/**
 * Retrieve symbol (e.g. function or data structure) with name @a symbol of
 * DLL @a hDLL .
 *
 * @param hDLL - handle of DLL
 * @param symbol - name of symbol to be accessed
 * @returns pointer to requested symbol or NULL on error
 */
void* DynamicLibraryGetSymbol(void* hDLL, String symbol);

/**
 * Unload the DLL given by @a hDLL , previously opened by e.g.
 * DynamicLibrariesSearch() or DynamicLibraryOpen() . If the DLL was opened
 * multiple times, then just the reference count is decremented and finally when
 * the reference count reached zero, the library is freed from memory.
 *
 * @param hDLL - handle of DLL to be closed
 */
void DynamicLibraryClose(void* hDLL);

} // namespace LinuxSampler

#endif // LS_DYNAMIC_LIBRARIES_H
1	schoenebeck	2124	/*
2			Copyright (C) 2010 Christian Schoenebeck
3			*/
4
5			#ifndef LS_DYNAMIC_LIBRARIES_H
6			#define LS_DYNAMIC_LIBRARIES_H
7
8			#include "Exception.h"
9			#include <string>
10
11			namespace LinuxSampler {
12
13			/**
14			* Function signature for callback functions used with function
15			* DynamicLibrariesSearch() .
16			*
17			* @param filename - full qualified filename of DLL
18			* @param hDLL - handle of opened DLL
19			* @param pFunction - pointer to requested function of DLL
20			* @param pCustom - (optional) custom data
21			*/
22			typedef void DynamicLibrariesSearchCallbackFunction(
23			String filename, void* hDLL, void* pFunction, void* pCustom
24			);
25
26			/**
27			* Search and load DLLs in the directory given by @a dir . For each DLL found,
28			* the library function supplied by @a funct is tried to be loaded and on
29			* success for each such DLL, the callback function @a pCallback is called.
30			*
31			* @e Note: This function leaves all DLLs open! You should close them once you
32			* don't need them anymore by calling DynamicLibraryClose() .
33			*
34			* @param dir - DLL directory
35			* @param funct - entry function to be loaded for each DLL
36			* @param pCallback - callback function which is called for each DLL found
37			* @param pCustom - (optional) arbitrary data passed to the callback function
38			* @throws Exception - if supplied directory cannot be opened
39			* @returns amount of DLLs loaded successfully
40			*/
41			int DynamicLibrariesSearch(String dir, String funct, DynamicLibrariesSearchCallbackFunction* pCallback, void* pCustom = NULL) throw (Exception);
42
43			/**
44			* Load the DLL given by @a filename . A DLL can be opened multiple times. A
45			* reference count is used in this case.
46			*
47			* @param filename - DLL to be loaded
48			* @returns handle to opened DLL or NULL on error
49			*/
50			void* DynamicLibraryOpen(String filename);
51
52			/**
53			* Retrieve symbol (e.g. function or data structure) with name @a symbol of
54			* DLL @a hDLL .
55			*
56			* @param hDLL - handle of DLL
57			* @param symbol - name of symbol to be accessed
58			* @returns pointer to requested symbol or NULL on error
59			*/
60			void* DynamicLibraryGetSymbol(void* hDLL, String symbol);
61
62			/**
63			* Unload the DLL given by @a hDLL , previously opened by e.g.
64			* DynamicLibrariesSearch() or DynamicLibraryOpen() . If the DLL was opened
65			* multiple times, then just the reference count is decremented and finally when
66			* the reference count reached zero, the library is freed from memory.
67			*
68			* @param hDLL - handle of DLL to be closed
69			*/
70			void DynamicLibraryClose(void* hDLL);
71
72			} // namespace LinuxSampler
73
74			#endif // LS_DYNAMIC_LIBRARIES_H