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
|
// -*- C++ -*-
//=============================================================================
/**
* @file DLL.h
*
* $Id$
*
* @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"
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 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 (int close_handle_on_destruction = 1);
/// 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,
int close_handle_on_destruction = 1);
/// 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.
* If a filename is given to @c open(), the @c ACE::ldfind() is used
* to locate DLLs via the following algorithms: (1) DLL filename
* expansion: @c ACE::ldfind() determines the name of the DLL by
* adding the appropriate prefix and suffix, e.g., it adds the @c lib
* prefix and @c .so suffix for Solaris and the @c .dll suffix for
* Windows and (2) DLL search path: @c ACE::ldfind() will also search
* for the designated DLL using the platform's DLL search path
* environment variable, e.g., it searches for DLLs using @c
* LD_LIBRARY_PATH on many UNIX systems and @c PATH on Windows.
* @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().
* @retval -1 On failure
* @retval 0 On success.
*/
int open (const ACE_TCHAR *dll_name,
int open_mode = ACE_DEFAULT_SHLIB_MODE,
int close_handle_on_destruction = 1);
/// 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 non-0 then
* caller assumes ownership of the handle and the ACE_DLL object
* won't call close() when it goes out of scope, even if
* <close_handle_on_destruction> is set.
*/
ACE_SHLIB_HANDLE get_handle (int become_owner = 0) 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,
int close_handle_on_destruction = 1);
private:
int open_i (const ACE_TCHAR *dll_name,
int open_mode = ACE_DEFAULT_SHLIB_MODE,
int close_handle_on_destruction = 1,
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.
int close_handle_on_destruction_;
ACE_DLL_Handle *dll_handle_;
/// Flag to record if the last operation had an error.
int error_;
};
ACE_END_VERSIONED_NAMESPACE_DECL
#include /**/ "ace/post.h"
#endif /* ACE_DLL_H */
|
