Document dns caching, add a "bool cached" to OnLookupComplete method in Resolver, and and add " -- cached" to end of 'looking up your host' string if their result is a cached result

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@6254 e03df62e-2008-0410-955e-edbf42e46eb7

3 files changed, 23 insertions, 3 deletions

diff --git a/include/dns.h b/include/dns.h
index bfced4184..c7283f6b8 100644
--- a/include/dns.h
+++ b/include/dns.h
@@ -228,6 +228,14 @@ class Resolver : public Extensible
 	 * To get around this automatic behaviour, you must use one of the values
 	 * DNS_QUERY_PTR4 or DNS_QUERY_PTR6 to force ipv4 or ipv6 behaviour on the lookup,
 	 * irrespective of what protocol InspIRCd has been built for.
+	 * @param cached The constructor will set this boolean to true or false depending
+	 * on whether the DNS lookup you are attempting is cached (and not expired) or not.
+	 * If the value is cached, upon return this will be set to true, otherwise it will
+	 * be set to false. You should pass this value to InspIRCd::AddResolver(), which
+	 * will then influence the behaviour of the method and determine whether a cached
+	 * or non-cached result is obtained. The value in this variable is always correct
+	 * for the given request when the constructor exits.
+	 * @param creator See the note below.
 	 * @throw ModuleException This class may throw an instance of ModuleException, in the
 	 * event a lookup could not be allocated, or a similar hard error occurs such as
 	 * the network being down. This will also be thrown if an invalid IP address is
@@ -247,8 +255,12 @@ class Resolver : public Extensible
 	/**
 	 * When your lookup completes, this method will be called.
 	 * @param result The resulting DNS lookup, either an IP address or a hostname.
+	 * @param ttl The time-to-live value of the result, in the instance of a cached
+	 * result, this is the number of seconds remaining before refresh/expiry.
+	 * @param cached True if the result is a cached result, false if it was requested
+	 * from the DNS server.
 	 */
-	virtual void OnLookupComplete(const std::string &result, unsigned int ttl) = 0;
+	virtual void OnLookupComplete(const std::string &result, unsigned int ttl, bool cached) = 0;
 	/**
 	 * If an error occurs (such as NXDOMAIN, no domain name found) then this method
 	 * will be called.
diff --git a/include/inspircd.h b/include/inspircd.h
index 136914276..2224dca63 100644
--- a/include/inspircd.h
+++ b/include/inspircd.h
@@ -885,7 +885,15 @@ class InspIRCd : public classbase
 
 	/** Add a dns Resolver class to this server's active set
 	 * @param r The resolver to add
-	 * @param cached The value of 'cached' which you passed to the Resolver constructor before this function.
+	 * @param cached If this value is true, then the cache will
+	 * be searched for the DNS result, immediately. If the value is
+	 * false, then a request will be sent to the nameserver, and the
+	 * result will not be immediately available. You should usually
+	 * use the boolean value which you passed to the Resolver
+	 * constructor, which Resolver will set appropriately depending
+	 * on if cached results are available and haven't expired. It is
+	 * however safe to force this value to false, forcing a remote DNS
+	 * lookup, but not an update of the cache.
 	 * @return True if the resolver was added
 	 */
         bool AddResolver(Resolver* r, bool cached);
diff --git a/include/users.h b/include/users.h
index c26d791fa..d69781f80 100644
--- a/include/users.h
+++ b/include/users.h
@@ -69,7 +69,7 @@ class UserResolver : public Resolver
  public:
 	UserResolver(InspIRCd* Instance, userrec* user, std::string to_resolve, QueryType qt, bool &cache);
 
-	void OnLookupComplete(const std::string &result, unsigned int ttl);
+	void OnLookupComplete(const std::string &result, unsigned int ttl, bool cached);
 	void OnError(ResolverError e, const std::string &errormessage);
 };