1//
2// SharedLibrary.h
3//
4// Library: Foundation
5// Package: SharedLibrary
6// Module: SharedLibrary
7//
8// Definition of the SharedLibrary class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_SharedLibrary_INCLUDED
18#define Foundation_SharedLibrary_INCLUDED
19
20
21#include "Poco/Foundation.h"
22
23
24#if defined(hpux) || defined(_hpux)
25#include "Poco/SharedLibrary_HPUX.h"
26#elif defined(POCO_VXWORKS)
27#include "Poco/SharedLibrary_VX.h"
28#elif defined(POCO_OS_FAMILY_UNIX)
29#include "Poco/SharedLibrary_UNIX.h"
30#elif defined(POCO_OS_FAMILY_WINDOWS)
31#include "Poco/SharedLibrary_WIN32.h"
32#endif
33
34
35namespace Poco {
36
37
38class Foundation_API SharedLibrary: private SharedLibraryImpl
39 /// The SharedLibrary class dynamically
40 /// loads shared libraries at run-time.
41{
42public:
43 enum Flags
44 {
45 SHLIB_GLOBAL = 1,
46 /// On platforms that use dlopen(), use RTLD_GLOBAL. This is the default
47 /// if no flags are given.
48 ///
49 /// This flag is ignored on platforms that do not use dlopen().
50
51 SHLIB_LOCAL = 2
52 /// On platforms that use dlopen(), use RTLD_LOCAL instead of RTLD_GLOBAL.
53 ///
54 /// Note that if this flag is specified, RTTI (including dynamic_cast and throw) will
55 /// not work for types defined in the shared library with GCC and possibly other
56 /// compilers as well. See http://gcc.gnu.org/faq.html#dso for more information.
57 ///
58 /// This flag is ignored on platforms that do not use dlopen().
59 };
60
61 SharedLibrary();
62 /// Creates a SharedLibrary object.
63
64 SharedLibrary(const std::string& path);
65 /// Creates a SharedLibrary object and loads a library
66 /// from the given path.
67
68 SharedLibrary(const std::string& path, int flags);
69 /// Creates a SharedLibrary object and loads a library
70 /// from the given path, using the given flags.
71 /// See the Flags enumeration for valid values.
72
73 virtual ~SharedLibrary();
74 /// Destroys the SharedLibrary. The actual library
75 /// remains loaded.
76
77 void load(const std::string& path);
78 /// Loads a shared library from the given path.
79 /// Throws a LibraryAlreadyLoadedException if
80 /// a library has already been loaded.
81 /// Throws a LibraryLoadException if the library
82 /// cannot be loaded.
83
84 void load(const std::string& path, int flags);
85 /// Loads a shared library from the given path,
86 /// using the given flags. See the Flags enumeration
87 /// for valid values.
88 /// Throws a LibraryAlreadyLoadedException if
89 /// a library has already been loaded.
90 /// Throws a LibraryLoadException if the library
91 /// cannot be loaded.
92
93 void unload();
94 /// Unloads a shared library.
95
96 bool isLoaded() const;
97 /// Returns true iff a library has been loaded.
98
99 bool hasSymbol(const std::string& name);
100 /// Returns true iff the loaded library contains
101 /// a symbol with the given name.
102
103 void* getSymbol(const std::string& name);
104 /// Returns the address of the symbol with
105 /// the given name. For functions, this
106 /// is the entry point of the function.
107 /// Throws a NotFoundException if the symbol
108 /// does not exist.
109
110 const std::string& getPath() const;
111 /// Returns the path of the library, as
112 /// specified in a call to load() or the
113 /// constructor.
114
115 static std::string prefix();
116 /// Returns the platform-specific filename prefix
117 /// for shared libraries.
118 /// Most platforms would return "lib" as prefix, while
119 /// on Cygwin, the "cyg" prefix will be returned.
120
121 static std::string suffix();
122 /// Returns the platform-specific filename suffix
123 /// for shared libraries (including the period).
124 /// In debug mode, the suffix also includes a
125 /// "d" to specify the debug version of a library.
126
127 static std::string getOSName(const std::string& name);
128 /// Returns the platform-specific filename
129 /// for shared libraries by prefixing and suffixing name
130 /// with prefix() and suffix()
131
132private:
133 SharedLibrary(const SharedLibrary&);
134 SharedLibrary& operator = (const SharedLibrary&);
135};
136
137
138} // namespace Poco
139
140
141#endif // Foundation_SharedLibrary_INCLUDED
142