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	/*
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