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