Commit 5f6cbcc3 authored by Jelte Jansen's avatar Jelte Jansen
Browse files

[trac494] some documentation

parent 92397738
......@@ -557,19 +557,39 @@ public:
int timeout = -1, unsigned retries = 0);
//@}
/// \brief Initiate resolving
///
/// When sendQuery() is called, a (set of) message(s) is sent
/// asynchronously. If upstream servers are set, one is chosen
/// and the response (if any) from that server will be returned.
///
/// If not upstream is set, a root server is chosen from the
/// root_servers, and the RunningQuery shall do a full resolve
/// (i.e. if the answer is a delegation, it will be followed, etc.)
/// until there is an answer or an error.
///
/// When there is a response or an error and we give up, the given
/// CallbackPtr object shall be called (with either success() or
/// failure(). See ResolverInterface::Callback for more information.
///
/// \param question The question being answered <qname/qclass/qtype>
/// \param callback Callback object
/// \param buffer An output Message into which the final response will be copied
/// \param buffer An output buffer into which the intermediate responses will be copied
/// \param server A pointer to the \c DNSServer object handling the client
void sendQuery(const isc::dns::QuestionPtr& question,
const isc::resolve::ResolverInterface::CallbackPtr callback);
/// \brief Initiates an upstream query in the \c RecursiveQuery object.
/// \brief Initiates resolving for the given question.
///
/// When sendQuery() is called, a message is sent asynchronously to
/// the upstream name server. When a reply arrives, 'server'
/// is placed on the ASIO service queue via io_service::post(), so
/// that the original \c DNSServer objct can resume processing.
/// This actually calls the previous sendQuery() with a default
/// callback object, which calls resume() on the given DNSServer
/// object.
///
/// \param question The question being answered <qname/qclass/qtype>
/// \param buffer An output buffer into which the response can be copied
/// \param buffer An output Message into which the final response will be copied
/// \param buffer An output buffer into which the intermediate responses will be copied
/// \param server A pointer to the \c DNSServer object handling the client
void sendQuery(const isc::dns::Question& question,
isc::dns::MessagePtr answer_message,
......
......@@ -18,7 +18,7 @@ namespace isc {
namespace resolve {
void
ResolverCallbackServer::success(isc::dns::MessagePtr response)
ResolverCallbackServer::success(const isc::dns::MessagePtr response)
{
// ignore our response here
(void)response;
......
......@@ -21,14 +21,21 @@
namespace isc {
namespace resolve {
/// \short Standard Callback for sendQuery for DNSServer instances
///
/// This is a standard ResolverInterface::Callback implementation
/// that is used by Resolver; when RunningQuery finishes and has either
/// some data or an error, DNSServer::resume() will be called.
///
/// This class will ignore the response MessagePtr in the callback,
/// as the server itself should also have a reference.
class ResolverCallbackServer : public ResolverInterface::Callback {
public:
ResolverCallbackServer(asiolink::DNSServer* server) :
server_(server->clone()) {}
~ResolverCallbackServer() { delete server_; };
//void callback(bool result);
void success(isc::dns::MessagePtr response);
void success(const isc::dns::MessagePtr response);
void failure();
private:
......
......@@ -41,22 +41,36 @@ namespace resolve {
*/
class ResolverInterface {
public:
/// \short An abstract callback when data from resolver are ready.
/// \short An abstract callback for when the resolver is done.
///
/// You can pass an instance of a subclass of this (as a
/// CallbackPtr) to RecursiveQuery::sendQuery(), and when it
/// is done, it will either call success() if there is an
/// answer MessagePtr, or failure(), if the resolver was not
/// able to find anything.
///
/// Note that a result Message does not necessarily contain
/// the actual answer (it could be a noerror/nodata response).
class Callback {
public:
/// \short Some data arrived.
virtual void success(isc::dns::MessagePtr response) = 0;
virtual void success(const isc::dns::MessagePtr response) = 0;
/**
* \short No data available.
*
* \todo Pass some reason.
* \todo Provide error reason (result of the
* classification call, for instance? We'd also
* need some way to say 'everything times out')
*/
virtual void failure() = 0;
/// \short Virtual destructor, so descendants are cleaned up
virtual ~ Callback() {};
virtual ~Callback() {};
};
typedef boost::shared_ptr<Callback> CallbackPtr;
/**
* \short Ask a question.
*
......@@ -68,6 +82,7 @@ class ResolverInterface {
*/
virtual void resolve(const isc::dns::QuestionPtr& question,
const CallbackPtr& callback) = 0;
/// \short Virtual destructor, so descendants are properly cleaned up
virtual ~ ResolverInterface() {}
};
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment