server_hooks.h 5.86 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

#ifndef SERVER_HOOKS_H
#define SERVER_HOOKS_H

#include <exceptions/exceptions.h>

Stephen Morris's avatar
Stephen Morris committed
20
21
#include <boost/noncopyable.hpp>

22
23
24
25
26
#include <map>
#include <string>
#include <vector>

namespace isc {
27
namespace hooks {
28

29
/// @brief Duplicate hook
30
31
32
33
34
35
36
37
38
///
/// Thrown if an attempt is made to register a hook with the same name as a
/// previously-registered hook.
class DuplicateHook : public Exception {
public:
    DuplicateHook(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

39
40
41
42
43
44
45
46
47
/// @brief Invalid hook
///
/// Thrown if an attempt is made to get the index for an invalid hook.
class NoSuchHook : public Exception {
public:
    NoSuchHook(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

48

49
/// @brief Server hook collection
50
///
51
52
53
54
/// This class is used by the server-side code to register hooks - points in the
/// server processing at which libraries can register functions (callouts) that
/// the server will call.  These functions can modify data and so affect the
/// processing of the server.
55
56
57
58
///
/// The ServerHooks class is little more than a wrapper around the std::map
/// class.  It stores a hook, assigning to it a unique index number.  This
/// number is then used by the server code to identify the hook being called.
59
60
61
/// (Although it would be feasible to use a name as an index, using an integer
/// will speed up the time taken to locate the callouts, which may make a
/// difference in a frequently-executed piece of code.)
Stephen Morris's avatar
Stephen Morris committed
62
63
///
/// ServerHooks is a singleton object and is only accessible by the static
Stephen Morris's avatar
Stephen Morris committed
64
/// method getServerHooks().
65

Stephen Morris's avatar
Stephen Morris committed
66
class ServerHooks : public boost::noncopyable {
67
68
public:

69
    /// Index numbers for pre-defined hooks.
70
71
72
    static const int CONTEXT_CREATE = 0;
    static const int CONTEXT_DESTROY = 1;

Stephen Morris's avatar
Stephen Morris committed
73
    /// @brief Reset to Initial State
74
    ///
Stephen Morris's avatar
Stephen Morris committed
75
76
77
78
    /// Resets the collection of hooks to the initial state, with just the
    /// context_create and context_destroy hooks set.  This used during
    /// construction. It is also used during testing to reset the global
    /// ServerHooks object.
79
80
81
    ///
    /// @throws isc::Unexpected if the registration of the pre-defined hooks
    ///         fails in some way.
Stephen Morris's avatar
Stephen Morris committed
82
    void reset();
83

84
    /// @brief Register a hook
85
86
87
88
89
    ///
    /// Registers a hook and returns the hook index.
    ///
    /// @param name Name of the hook
    ///
90
91
92
    /// @return Index of the hook, to be used in subsequent hook-related calls.
    ///         This will be greater than or equal to zero (so allowing a
    ///         negative value to indicate an invalid index).
93
94
95
96
97
    ///
    /// @throws DuplicateHook A hook with the same name has already been
    ///         registered.
    int registerHook(const std::string& name);

Stephen Morris's avatar
Stephen Morris committed
98
99
100
101
102
103
104
105
106
107
108
109
    /// @brief Get hook name
    ///
    /// Returns the name of a hook given the index.  This is most likely to be
    /// used in log messages.
    ///
    /// @param index Index of the hoold
    ///
    /// @return Name of the hook.
    ///
    /// @throw NoSuchHook if the hook index is invalid.
    std::string getName(int index) const;

110
    /// @brief Get hook index
111
112
113
114
115
    ///
    /// Returns the index of a hook.
    ///
    /// @param name Name of the hook
    ///
116
117
118
    /// @return Index of the hook, to be used in subsequent calls.
    ///
    /// @throw NoSuchHook if the hook name is unknown to the caller.
119
120
    int getIndex(const std::string& name) const;

121
    /// @brief Return number of hooks
122
123
124
125
126
127
128
129
    ///
    /// Returns the total number of hooks registered.
    ///
    /// @return Number of hooks registered.
    int getCount() const {
        return (hooks_.size());
    }

130
    /// @brief Get hook names
131
132
133
134
135
136
    ///
    /// Return list of hooks registered in the object.
    ///
    /// @return Vector of strings holding hook names.
    std::vector<std::string> getHookNames() const;

Stephen Morris's avatar
Stephen Morris committed
137
    /// @brief Return ServerHooks object
Stephen Morris's avatar
Stephen Morris committed
138
139
140
141
142
143
    ///
    /// Returns the global ServerHooks object.
    ///
    /// @return Reference to the global ServerHooks object.
    static ServerHooks& getServerHooks();

144
private:
Stephen Morris's avatar
Stephen Morris committed
145
146
147
148
149
150
151
152
153
    /// @brief Constructor
    ///
    /// This pre-registers two hooks, context_create and context_destroy, which
    /// are called by the server before processing a packet and after processing
    /// for the packet has completed.  They allow the server code to allocate
    /// and destroy per-packet context.
    ///
    /// Constructor is declared private to enforce the singleton nature of
    /// the object.  A reference to the singleton is obtainable through the
154
    /// getServerHooks() static method.
Stephen Morris's avatar
Stephen Morris committed
155
156
157
158
159
160
    ///
    /// @throws isc::Unexpected if the registration of the pre-defined hooks
    ///         fails in some way.
    ServerHooks();

    /// Useful typedefs.
161
    typedef std::map<std::string, int> HookCollection;
Stephen Morris's avatar
Stephen Morris committed
162
    typedef std::map<int, std::string> InverseHookCollection;
163

Stephen Morris's avatar
Stephen Morris committed
164
165
166
167
    /// Two maps, one for name->index, the other for index->name.  (This is
    /// simpler than using a multi-indexed container.)
    HookCollection  hooks_;                 ///< Hook name/index collection
    InverseHookCollection inverse_hooks_;   ///< Hook index/name collection
168
169
170
171
172
173
};

} // namespace util
} // namespace isc

#endif  // SERVER_HOOKS_H