1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
// -*- C++ -*-
//=============================================================================
/**
* @file DLL.h
*
* @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
*/
//=============================================================================
#ifndef ACE_DLL_H
#define ACE_DLL_H
#include /**/ "ace/pre.h"
#include /**/ "ace/ACE_export.h"
#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */
#include "ace/Global_Macros.h"
#include "ace/os_include/os_dlfcn.h"
#include "ace/SString.h"
ACE_BEGIN_VERSIONED_NAMESPACE_DECL
class ACE_DLL_Handle;
/**
* @class ACE_DLL
*
* @brief Provides an abstract interface for handling various DLL
* operations.
*
* This class is a wrapper over the various methods for utilizing
* a dynamically linked library (DLL), which is called a shared
* library on some platforms. Operations @c open(), @c close(), and
* @c symbol() have been implemented to help opening/closing and
* extracting symbol information from a DLL, respectively.
*/
class ACE_Export ACE_DLL
{
public:
// = Initialization and termination methods.
/**
* Default constructor. By default, the close() operation on the
* object will be invoked before it is destroyed.
* @param close_handle_on_destruction Indicates whether or not the
* close() method will be called to close an open DLL when this
* object is destroyed. By default, close() will be called.
* Set this parameter to false for situations where the DLL's lifetime
* is controlled in a scope other than that of this ACE_DLL object.
* For example, termination by ACE_DLL_Manager via ACE::fini().
*/
explicit ACE_DLL (bool close_handle_on_destruction = true);
/// Allow assignment
ACE_DLL& operator= (const ACE_DLL &rhs);
/**
* This constructor performs the actions of open() during construction.
* @param dll_name The name or path of the DLL to load.
* @param open_mode Flags to alter the actions taken when loading the DLL.
* The possible values are:
* @li @c RTLD_LAZY (this the default): loads identifier symbols but
* not the symbols for functions, which are loaded dynamically
* on-demand.
* @li @c RTLD_NOW: performs all necessary relocations when
* @a dll_name is first loaded
* @li RTLD_GLOBAL: makes symbols available for relocation
* processing of any other DLLs.
* @param close_handle_on_destruction Indicates whether or not the
* close() method will be called to close an open DLL when this
* object is destroyed. By default, close() will be called.
* Set this parameter to 0 for situations where the DLL's lifetime
* is controlled in a scope other than that of this ACE_DLL object.
* For example, termination by ACE_DLL_Manager via ACE::fini().
*/
explicit ACE_DLL (const ACE_TCHAR *dll_name,
int open_mode = ACE_DEFAULT_SHLIB_MODE,
bool close_handle_on_destruction = true);
/// Copy constructor.
ACE_DLL (const ACE_DLL &);
/**
* This method opens and dynamically links a specified DLL.
* @param dll_name The filename or path of the DLL to load. ACE will
* attempt to apply the platform's standard library/DLL prefixes
* and suffixes, allowing a simple, unadorned name to be passed
* regardless of platform. The set of name transforms is listed
* below. A @i decorator is a platform's name designator for a debug
* vs release build. For example, on Windows it is usually "d".
* @li Prefix + name + decorator + suffix
* @li Prefix + name + suffix
* @li Name + decorator + suffix
* @li Name + suffix
* @li Name
* Note that the transforms with @i decorator will be avoided if
* ACE is built with the @c ACE_DISABLE_DEBUG_DLL_CHECK config macro.
*
* @Note There is another mode for locating library/DLL files that
* was used in old versions of ACE. The alternate method builds
* more combinations of pathname by combining the names transforms
* above with locations listed in the platform's standard "path"
* locations (e.g., @c LD_LIBRARY_PATH). It can be enabled by building
* ACE with the @c ACE_MUST_HELP_DLOPEN_SEARCH_PATH config macro.
* Use of this option is discouraged since it avoids the standard
* platform search options and security mechanisms.
*
* @param open_mode Flags to alter the actions taken when loading the DLL.
* The possible values are:
* @li @c RTLD_LAZY (this the default): loads identifier symbols but
* not the symbols for functions, which are loaded dynamically
* on demand.
* @li @c RTLD_NOW: performs all necessary relocations when
* @a dll_name is first loaded
* @li @c RTLD_GLOBAL: makes symbols available for relocation
* processing of any other DLLs.
* @param close_handle_on_destruction Indicates whether or not the
* close() method will be called to close an open DLL when this
* object is destroyed. By default, close() will be called.
* Set this parameter to 0 for situations where the DLL's lifetime
* is controlled in a scope other than that of this ACE_DLL object.
* For example, termination by ACE_DLL_Manager via ACE::fini().
* @retval -1 On failure
* @retval 0 On success.
*/
int open (const ACE_TCHAR *dll_name,
int open_mode = ACE_DEFAULT_SHLIB_MODE,
bool close_handle_on_destruction = true);
/// Call to close the DLL object.
int close (void);
/**
* Called when the DLL object is destroyed -- invokes close() if the
* @a close_handle_on_destruction flag was set to non-zero in the
* constructor or open() method.
*/
~ACE_DLL (void);
/**
* Look up a named symbol in the DLL. DLL must be successfully opened
* before calling symbol().
* @param symbol_name The symbol name to look up.
* @param ignore_errors If set to 1, allows you to probe a dll without
* generating error messages in the log. Handy for determining
* the capabilities of a library.
* @return Returns the value of @a symbol_name if it is a valid symbol
* in the DLL. Otherwise, returns 0.
*/
void *symbol (const ACE_TCHAR *symbol_name, int ignore_errors = 0);
/// Returns a pointer to a string explaining that an error occured. You
/// will need to consult the error log for the actual error string
/// returned by the OS.
ACE_TCHAR *error (void) const;
/**
* Return the handle to the caller. If @a become_owner is true then
* caller assumes ownership of the handle and the ACE_DLL object
* won't call close() when it goes out of scope, even if
* @c close_handle_on_destruction is set.
*/
ACE_SHLIB_HANDLE get_handle (bool become_owner = false) const;
/// Set the handle for the DLL object. By default, the close()
/// operation on / the object will be invoked before it is destroyed.
int set_handle (ACE_SHLIB_HANDLE handle,
bool close_handle_on_destruction = true);
private:
int open_i (const ACE_TCHAR *dll_name,
int open_mode = ACE_DEFAULT_SHLIB_MODE,
bool close_handle_on_destruction = true,
ACE_SHLIB_HANDLE handle = 0);
//private:
public:
/// Open mode.
int open_mode_;
/// Keep track of the name of the loaded dll, so it can be used
/// to remove framework components, singletons that live in the dll,
/// prior to unloading the dll in the close() method.
ACE_TCHAR *dll_name_;
/// This flag keeps track of whether we should close the handle
/// automatically when the object is destroyed.
bool close_handle_on_destruction_;
ACE_DLL_Handle *dll_handle_;
/// Flag to record if the last operation had an error.
bool error_;
/// Any error messages encountered during last operation.
ACE_TString errmsg_;
};
ACE_END_VERSIONED_NAMESPACE_DECL
#include /**/ "ace/post.h"
#endif /* ACE_DLL_H */
|
