Branch data Line data Source code
1 : : // Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC")
2 : : //
3 : : // Permission to use, copy, modify, and/or distribute this software for any
4 : : // purpose with or without fee is hereby granted, provided that the above
5 : : // copyright notice and this permission notice appear in all copies.
6 : : //
7 : : // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8 : : // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9 : : // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
10 : : // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
11 : : // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
12 : : // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
13 : : // PERFORMANCE OF THIS SOFTWARE.
14 : :
15 : : #ifndef __ASIOLINK_DNS_SERVICE_H
16 : : #define __ASIOLINK_DNS_SERVICE_H 1
17 : :
18 : : #include <resolve/resolver_interface.h>
19 : :
20 : : #include <asiolink/io_service.h>
21 : : #include <asiolink/simple_callback.h>
22 : :
23 : : namespace isc {
24 : : namespace asiodns {
25 : :
26 : : class DNSLookup;
27 : : class DNSAnswer;
28 : : class DNSServiceImpl;
29 : :
30 : : /// \brief A base class for common \c DNSService interfaces.
31 : : ///
32 : : /// This class is defined mainly for test code so it can use a faked/mock
33 : : /// version of a derived class and test scenarios that would involve
34 : : /// \c DNSService without actually instantiating the real service class.
35 : : ///
36 : : /// It doesn't intend to be a customization for other purposes - we generally
37 : : /// expect non test code only use \c DNSService directly.
38 : : /// For this reason most of the detailed description are given in the
39 : : /// \c DNSService class. See that for further details of specific methods
40 : : /// and class behaviors.
41 : : class DNSServiceBase {
42 : : protected:
43 : : /// \brief Default constructor.
44 : : ///
45 : : /// This is protected so this class couldn't be accidentally instantiated
46 : : /// directly, even if there were no pure virtual functions.
47 : 150 : DNSServiceBase() {}
48 : :
49 : : public:
50 : : /// \brief Flags for optional server properties.
51 : : ///
52 : : /// The values of this enumerable type are intended to be used to specify
53 : : /// a particular property of the server created via the \c addServer
54 : : /// variants. As we see need for more such properties, a compound
55 : : /// form of flags (i.e., a single value generated by bitwise OR'ed
56 : : /// multiple flag values) will be allowed.
57 : : ///
58 : : /// Note: the description is given here because it's used in the method
59 : : /// signature. It essentially belongs to the derived \c DNSService
60 : : /// class.
61 : : enum ServerFlag {
62 : : SERVER_DEFAULT = 0, ///< The default flag (no particular property)
63 : : SERVER_SYNC_OK = 1 ///< The server can act in the "synchronous" mode.
64 : : ///< In this mode, the client ensures that the
65 : : ///< lookup provider always completes the query
66 : : ///< process and it immediately releases the
67 : : ///< ownership of the given buffer. This allows
68 : : ///< the server implementation to introduce some
69 : : ///< optimization such as omitting unnecessary
70 : : ///< operation or reusing internal resources.
71 : : ///< Note that in functionality the non
72 : : ///< "synchronous" mode is compatible with the
73 : : ///< synchronous mode; it's up to the server
74 : : ///< implementation whether it exploits the
75 : : ///< information given by the client.
76 : : };
77 : :
78 : : public:
79 : : /// \brief The destructor.
80 : 150 : virtual ~DNSServiceBase() {}
81 : :
82 : : virtual void addServerTCPFromFD(int fd, int af) = 0;
83 : : virtual void addServerUDPFromFD(int fd, int af,
84 : : ServerFlag options = SERVER_DEFAULT) = 0;
85 : : virtual void clearServers() = 0;
86 : :
87 : : virtual asiolink::IOService& getIOService() = 0;
88 : : };
89 : :
90 : : /// \brief Handle DNS Queries
91 : : ///
92 : : /// DNSService is the service that handles DNS queries and answers with
93 : : /// a given IOService. This class is mainly intended to hold all the
94 : : /// logic that is shared between the authoritative and the recursive
95 : : /// server implementations. As such, it handles asio, including config
96 : : /// updates (through the 'Checkinprovider'), and listening sockets.
97 : : class DNSService : public DNSServiceBase {
98 : : ///
99 : : /// \name Constructors and Destructor
100 : : ///
101 : : /// Note: The copy constructor and the assignment operator are
102 : : /// intentionally defined as private, making this class non-copyable.
103 : : //@{
104 : : private:
105 : : DNSService(const DNSService& source);
106 : : DNSService& operator=(const DNSService& source);
107 : :
108 : : private:
109 : : // Bit or'ed all defined \c ServerFlag values. Used internally for
110 : : // compatibility check. Note that this doesn't have to be used by
111 : : // applications, and doesn't have to be defined in the "base" class.
112 : : static const unsigned int SERVER_DEFINED_FLAGS = 1;
113 : :
114 : : public:
115 : : /// \brief The constructor without any servers.
116 : : ///
117 : : /// Use addServerTCPFromFD() or addServerUDPFromFD() to add some servers.
118 : : ///
119 : : /// \param io_service The IOService to work with
120 : : /// \param checkin Provider for cc-channel events (see \c SimpleCallback)
121 : : /// \param lookup The lookup provider (see \c DNSLookup)
122 : : /// \param answer The answer provider (see \c DNSAnswer)
123 : : DNSService(asiolink::IOService& io_service,
124 : : isc::asiolink::SimpleCallback* checkin,
125 : : DNSLookup* lookup, DNSAnswer* answer);
126 : :
127 : : /// \brief The destructor.
128 : : virtual ~DNSService();
129 : : //@}
130 : :
131 : : /// \brief Add another TCP server/listener to the service from already
132 : : /// opened file descriptor
133 : : ///
134 : : /// Adds a new TCP server using an already opened file descriptor (eg. it
135 : : /// only wraps it so the file descriptor is usable within the event loop).
136 : : /// The file descriptor must be associated with a TCP socket of the given
137 : : /// address family that is bound to an appropriate port (and possibly a
138 : : /// specific address) and is ready for listening to new connection
139 : : /// requests but has not actually started listening.
140 : : ///
141 : : /// At the moment, TCP servers don't support any optional properties;
142 : : /// so unlike the UDP version of the method it doesn't have an \c options
143 : : /// argument.
144 : : ///
145 : : /// \param fd the file descriptor to be used.
146 : : /// \param af the address family of the file descriptor. Must be either
147 : : /// AF_INET or AF_INET6.
148 : : /// \throw isc::InvalidParameter if af is neither AF_INET nor AF_INET6.
149 : : /// \throw isc::asiolink::IOError when a low-level error happens, like the
150 : : /// fd is not a valid descriptor or it can't be listened on.
151 : : virtual void addServerTCPFromFD(int fd, int af);
152 : :
153 : : /// \brief Add another UDP server to the service from already opened
154 : : /// file descriptor
155 : : ///
156 : : /// Adds a new UDP server using an already opened file descriptor (eg. it
157 : : /// only wraps it so the file descriptor is usable within the event loop).
158 : : /// The file descriptor must be associated with a UDP socket of the given
159 : : /// address family that is bound to an appropriate port (and possibly a
160 : : /// specific address).
161 : : ///
162 : : /// \param fd the file descriptor to be used.
163 : : /// \param af the address family of the file descriptor. Must be either
164 : : /// AF_INET or AF_INET6.
165 : : /// \param options Optional properties of the server (see ServerFlag).
166 : : ///
167 : : /// \throw isc::InvalidParameter if af is neither AF_INET nor AF_INET6,
168 : : /// or the given \c options include an unsupported or invalid value.
169 : : /// \throw isc::asiolink::IOError when a low-level error happens, like the
170 : : /// fd is not a valid descriptor or it can't be listened on.
171 : : virtual void addServerUDPFromFD(int fd, int af,
172 : : ServerFlag options = SERVER_DEFAULT);
173 : :
174 : : /// \brief Remove all servers from the service
175 : : void clearServers();
176 : :
177 : : /// \brief Return the native \c io_service object used in this wrapper.
178 : : ///
179 : : /// This is a short term work around to support other BIND 10 modules
180 : : /// that share the same \c io_service with the authoritative server.
181 : : /// It will eventually be removed once the wrapper interface is
182 : : /// generalized.
183 : : asio::io_service& get_io_service() { return io_service_.get_io_service(); }
184 : :
185 : : /// \brief Return the IO Service Object
186 : : ///
187 : : /// \return IOService object for this DNS service.
188 : 8 : virtual asiolink::IOService& getIOService() { return (io_service_);}
189 : :
190 : : private:
191 : : DNSServiceImpl* impl_;
192 : : asiolink::IOService& io_service_;
193 : : };
194 : :
195 : : } // namespace asiodns
196 : : } // namespace isc
197 : : #endif // __ASIOLINK_DNS_SERVICE_H
198 : :
199 : : // Local Variables:
200 : : // mode: c++
201 : : // End:
|
