Resolver Class Reference

The Resolver class is a high-level abstraction for resolving DNS entries. More...

#include <dns.h>

Inheritance diagram for Resolver:

[legend]Collaboration diagram for Resolver:

[legend]List of all members.


Public Member Functions
	Resolver (InspIRCd Instance, const std::string &source, QueryType qt, bool &cached, Module creator=NULL)
	Initiate DNS lookup.
virtual	~Resolver ()
	The default destructor does nothing.
virtual void	OnLookupComplete (const std::string &result, unsigned int ttl, bool cached, int resultnum=0)=0
	When your lookup completes, this method will be called.
virtual void	OnError (ResolverError e, const std::string &errormessage)
	If an error occurs (such as NXDOMAIN, no domain name found) then this method will be called.
int	GetId ()
	Returns the id value of this class.
Module *	GetCreator ()
	Returns the creator module, or NULL.
void	TriggerCachedResult ()
	If the result is a cached result, this triggers the objects OnLookupComplete.
Protected Attributes
InspIRCd *	ServerInstance
	Pointer to creator.
Module *	Creator
	Pointer to creator module (if any, or NULL).
std::string	input
	The input data, either a host or an IP address.
QueryType	querytype
	True if a forward lookup is being performed, false if otherwise.
std::string	server
	The DNS erver being used for lookups.
int	myid
	The ID allocated to your lookup.
CachedQuery *	CQ
	Cached result, if there is one.
int	time_left
	Time left before cache expiry.

Detailed Description

The Resolver class is a high-level abstraction for resolving DNS entries.

It can do forward and reverse IPv4 lookups, and where IPv6 is supported, will also be able to do those, transparent of protocols. Module developers must extend this class via inheritence, and then insert a pointer to their derived class into the core using Server::AddResolver(). Once you have done this, the class will be able to receive callbacks. There are two callbacks which can occur by calling virtual methods, one is a success situation, and the other an error situation.

Definition at line 182 of file dns.h.

Constructor & Destructor Documentation

Resolver::Resolver ( InspIRCd * Instance,

const std::string & source,

QueryType qt,

bool & cached,

Module * creator = NULL

)

Initiate DNS lookup.
Your class should not attempt to delete or free these objects, as the core will do this for you. They must always be created upon the heap using new, as you cannot be sure at what time they will be deleted. Allocating them on the stack or attempting to delete them yourself could cause the object to go 'out of scope' and cause a segfault in the core if the result arrives at a later time.
Parameters:

source The IP or hostname to resolve

qt The query type to perform. If you just want to perform a forward or reverse lookup, and you don't care wether you get ipv4 or ipv6, then use the constants DNS_QUERY_FORWARD and DNS_QUERY_REVERSE, which automatically select from 'A' record or 'AAAA' record lookups. However, if you want to resolve a specific record type, resolution of 'A', 'AAAA', 'PTR' and 'CNAME' records is supported. Use one of the QueryType enum values to initiate this type of lookup. Resolution of 'AAAA' ipv6 records is always supported, regardless of wether InspIRCd is built with ipv6 support. If you attempt to resolve a 'PTR' record using DNS_QUERY_PTR, and InspIRCd is built with ipv6 support, the 'PTR' record will be formatted to ipv6 specs, e.g. x.x.x.x.x....ip6.arpa. otherwise it will be formatted to ipv4 specs, e.g. x.x.x.x.in-addr.arpa. This translation is automatic. 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.

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.

creator See the note below.

Exceptions:

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 passed when resolving a 'PTR' record.

NOTE: If you are instantiating your DNS lookup from a module, you should set the value of creator to point at your Module class. This way if your module is unloaded whilst lookups are in progress, they can be safely removed and your module will not crash the server.
Definition at line 960 of file dns.cpp.
References CachedQuery::CalcTTLRemaining(), CQ, DEBUG, DNS::DelCache(), DNS_QUERY_A, DNS_QUERY_AAAA, DNS_QUERY_CNAME, DNS_QUERY_PTR, DNS_QUERY_PTR4, DNS_QUERY_PTR6, DNS::GetCache(), DNS::GetCName(), DNS::GetIP(), DNS::GetIP6(), DNS::GetName(), DNS::GetNameForce(), irc::sockets::insp_aton(), LogManager::Log(), InspIRCd::Logs, myid, OnError(), PROTOCOL_IPV4, PROTOCOL_IPV6, querytype, InspIRCd::Res, RESOLVER_BADIP, RESOLVER_NSDOWN, ServerInstance, and time_left.

Resolver::~Resolver ( ) [virtual]

The default destructor does nothing.

Definition at line 1044 of file dns.cpp.

Member Function Documentation

Module * Resolver::GetCreator ( )

Returns the creator module, or NULL.

Definition at line 1055 of file dns.cpp.
References Creator.

int Resolver::GetId ( )

Returns the id value of this class.
This is primarily used by the core to determine where in various tables to place a pointer to your class, but it is safe to call and use this method. As specified in RFC1035, each dns request has a 16 bit ID value, ranging from 0 to 65535. If there is an issue and the core cannot send your request, this method will return -1.
Definition at line 1050 of file dns.cpp.
References myid.
Referenced by DNS::AddResolverClass().

void Resolver::OnError ( ResolverError e,

const std::string & errormessage

) [virtual]

If an error occurs (such as NXDOMAIN, no domain name found) then this method will be called.

Parameters:

e A ResolverError enum containing the error type which has occured.

errormessage The error text of the error that occured.

Reimplemented in CGIResolver, DNSBLResolver, SQLresolver, SecurityIPResolver, ServernameResolver, and UserResolver.
Definition at line 1038 of file dns.cpp.
Referenced by DNS::CleanResolvers(), DNS::HandleEvent(), Resolver(), and RequestTimeout::Tick().

virtual void Resolver::OnLookupComplete ( const std::string & result,

unsigned int ttl,

bool cached,

int resultnum = 0

) [pure virtual]

When your lookup completes, this method will be called.

Parameters:

result The resulting DNS lookup, either an IP address or a hostname.

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.

cached True if the result is a cached result, false if it was requested from the DNS server.

resultnum Result number, for records with multiple matching results. Normally, you will only want to act on this when the result is 0.

Implemented in CGIResolver, DNSBLResolver, SQLresolver, SecurityIPResolver, ServernameResolver, and UserResolver.
Referenced by DNS::HandleEvent(), and TriggerCachedResult().

void Resolver::TriggerCachedResult ( )

If the result is a cached result, this triggers the objects OnLookupComplete.
This is done because it is not safe to call the abstract virtual method from the constructor.
Definition at line 953 of file dns.cpp.
References CQ, CachedQuery::data, OnLookupComplete(), and time_left.

Member Data Documentation

CachedQuery* Resolver::CQ [protected]

Cached result, if there is one.

Definition at line 216 of file dns.h.
Referenced by Resolver(), and TriggerCachedResult().

Module* Resolver::Creator [protected]

Pointer to creator module (if any, or NULL).

Definition at line 192 of file dns.h.
Referenced by GetCreator().

std::string Resolver::input [protected]

The input data, either a host or an IP address.

Definition at line 196 of file dns.h.

int Resolver::myid [protected]

The ID allocated to your lookup.
This is a pseudo-random number between 0 and 65535, a value of -1 indicating a failure. The core uses this to route results to the correct objects.
Definition at line 211 of file dns.h.
Referenced by GetId(), and Resolver().

QueryType Resolver::querytype [protected]

True if a forward lookup is being performed, false if otherwise.

Definition at line 200 of file dns.h.
Referenced by Resolver().

std::string Resolver::server [protected]

The DNS erver being used for lookups.
If this is an empty string, the value of ServerConfig::DNSServer is used instead.
Definition at line 205 of file dns.h.

InspIRCd* Resolver::ServerInstance [protected]

Pointer to creator.

Definition at line 188 of file dns.h.
Referenced by UserResolver::OnError(), SecurityIPResolver::OnError(), ServernameResolver::OnError(), SQLresolver::OnError(), CGIResolver::OnError(), UserResolver::OnLookupComplete(), ServernameResolver::OnLookupComplete(), DNSBLResolver::OnLookupComplete(), CGIResolver::OnLookupComplete(), and Resolver().

int Resolver::time_left [protected]

Time left before cache expiry.

Definition at line 221 of file dns.h.
Referenced by Resolver(), and TriggerCachedResult().

The documentation for this class was generated from the following files:

Resolver Class Reference

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation