// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// listener.h - name resolver query dispatcher header

//

#ifndef __LISTENER_H__

#define __LISTENER_H__

/**

@file listener.h

Dispatch resolve requests to resolvers

@internalComponent	Domain Name Resolver

*/

#include <es_sock.h>

#include <in_sock.h>

#include "dns_hdr.h"

#include "servers.h"

#include "res_sock.h"

/**

@mainpage	Domain Name Resolver Daemon (DND)

@section	overview	Overview

  The EPOC32 differs architecturally from the usual Unix resolver

  library implementations:

@li

  Traditionally on Unix, the resolver library is linked with the application and from

  the view point of the kernel, the application is just using additional sockets to

  communicate with the name servers.

@li

  on EPOC32, the name name resolver for the internet is implemented by the TCP/IP

  protocol module, and is shared by all applications. Applications only establish

  a session to this service via RHostResolver class. EPOC32 has standardised the

  resolver interface, and each protocol can have its own implementation of the

  service (with TCPIP protocol, all protocols use the same instance of the name

  resolver).

  The IPv6/Ipv4 stack does not contain the name resolution code. Instead,

  it provides a special socket API for a protocol named <b>resolver</b>, which

  is used by an external server application providing the actual implementation

  of the name resolution.

  The stack maintains a <b>communication path</b> or session between user

  RHostResolver and the resolver instance within the name resolver implementation.

  This path is a chain of objects starting from the RHostResolver and ending

  into CDndResolver, which performs the real name resolution using the other

  modules of the name resolver application:

@verbatim

  RHostResolver (application -> Socket Server)

    CHostResolver (Socket Server -> TCPIP stack)

      CDndSession (TCPIP stack -> gateway socket)

        RSocket (gateway socket -> resolver application)

          CDndResolver (resolver instance)

          - use host files

          - use UDP sockets to communicate with DNS servers

@endverbatim

  The name resolver is a <b>server application</b> listening to the incoming

  requests from a special <b>resolver</b> socket.

  When an application requests a name resolution via some RHostResolver

  method (GetByName, GetByAddress or Query), the resolver gateway code

  in the stack (res.cpp) translates this into a message which is received

  by the DND listener. The message includes a session id, which is assigned

  by the resolver gateway. TDnsRequestBase defines the basic message format.

  The name resolver receives the request and uses the session id in choosing

  the correct resolver instance to serve the request. If a session does not

  yet have a resolver, it will be allocated.

  The resolver processes the request and returns the result as a reply

  message to the socket. The resolver gateway will then translate the result

  into RHostResolver completion.

@section	components	Major components of the implementation

@verbatim

Application                .

===================== RHostResolver ==========

Socket Server              .

===================== CHostResolver ==========

TCPIP Stack                .

                       CDndSession

           resolver        .

            gateway   (session id)

============ socket ===========================

DND                   (session id)

                           .

     main                  .

       \                   .

       engine              .

       /  \                .

      /    \               .

   hosts    \              .

   file    listener        .

           /   |  \        .

          /    |    \      .

         /     |      \    .

   DNS  /     DNS       \  .

 servers   protocol    resolvers

 manager  /  . |  . .    . .

         /  .  |   . .  . .

        /  .  DNS   . .. .

  (LLMNR) .  cache   query

       . .          sessions

        .

        .

     UDP/TCP

==== socket(s) =================================

        .

        .

      remote

     DNS Server

@endverbatim

@subsection	main		Main component

  The <b>main</b> contains the necessary glue and wrappings that are required to

  run an application under EPOC32. The main implements the user interface of

  the application. The standard DND is run as a <b>daemon process</b> and there

  is no real user interface. However, the architecture also allows one to

  write a main module with full user interface, if desired.

  The MDemonMain class defines the services which are required by the

  resolver implementation (engine) from the main module.

@subsection	engine		Engine component

  The <b>engine</b> contains usually the implementation of the application.

  This is intended to be independent of the user interface. The class

  MDemonEngine defines the API from engine to the <b>main</b>.

  In the name resolver implementation, the <b>engine</b> module is left as an

  intermediate between the real implementation in the listener and the main

  module. The CDndEngine is passed as the <b>control</b> instance to almost every

  other component of the resolver implementation. <b>Engine</b> creates and owns

  some common resources, for example: timer service (MTimeoutManager),

  host files handler (RHostsFile) and the configuration

  parameters (TDndConfigParameters).

@subsection	listener	Listener component

  The listener (CDndListener) is the real <b>main program</b> of the name

  resolver implementation. If opens the socket and listens to the

  incoming request messages.

  Using the session id, the listener delegates the task of

  serving the session to an available resolver instance (CDndResolver).

@subsection	resolvers	Resolver component

  The <b>resolver</b> (CDndResolver) serves one RHostResolver session at time.

  The same session may serve different RHostResolver's at different times.

  It receives the requests from the gateway socket via the listener.

  The resolver state diagram is roughly

@verbatim

     Start

       |----------------> Stop

     Receive a Query

       |----------------> Stop

     Return first result

       |

   +-->|

   |   | - - -> listener forced Stop

   |   |

   |   |----------------> Stop

   | Receive Next Query

   |   |----------------> Stop

   | Return next result

   +---|

     Stop

@endverbatim

  Because many applications are only interested about the first result,

  and because they often leave the RHostResolver session(s) open, the

  gateway may sometimes <em>steal a session for a new RHostResolver</em>,

  if all resolvers are already busy. The oldest resolver that has returned

  at least one answer is assigned to the new RHostResolver.

  The "stealing action" action does not harm the application in any other way,

  except that if it now tries to call Next(), it will return an error. If

  such application issues a new query (GetByName, GetByAddress or Query),

  a new resolver is just assigned to serve it.

  The resolver session is always stopped, after query has

  completed (no further answers are available).

  The resolver performs its work by establishing a number of query

  sessions (MDnsSession) with the DNS protocol module. The progress

  of an active query session is reported through callbacks

  (MDnsResolver).

@subsection	hosts		Host File component

  The hosts file handler (RHostsFile) provides the service for looking an

  answer from the local hosts file (if any is present). Only the GetByName

  or GetByAddr queries can be satisfied from the hosts file. The "hosts"

  file has a very simple format which binds a name to an address,

  for example:

@verbatim

127.0.0.1 localhost

10.0.0.2 server

10.0.0.3 server

10.0.0.3 alternatename

fe80::dead:beef local-beef

::1 localhost6

ff02::1 allnodes6

ff02::2 allrouters6

ff02::3 allhosts6

@endverbatim

@subsection dnsclient	DNS Protocol implementation

  The DNS procotol is implemented by CDndDnsclient class (or by some derived class). The

  class exports MDnsSource API, which is used by the resolvers to start query sessions

  (MDnsSession), which send and receive the actual DNS protocol messages.

@subsection	llmnr		Link Local Multicast Name Resolution

  The link local multicast name resolution uses the DNS protocol with link local

  multicast. The DNS protocol messages are sent to the link with multicast

  destinations and a node that owns the queried name, will respond as if it

  was a DNS server.

  When LLMNR is compiled in, the DNS protocol is implemented by CDndLlmnrSender

  class, which is derived from the CDndDnsclient. This class extends the normal

  DNS with the link local multicast name resolution additions.

@subsection	servers		Server Manager component

  The server manager (MDnsServerManager) maintains the list of currently known and

  avalable DNS servers. The content of the list may be constantly changing depending

  on which interfaces are active at any particular point of time. The issues are even

  more complicated by the fact that initially there are no interfaces up (or at least,

  there may be no known servers), and name resolver just has to wait until something

  becomes available.

@subsection cache		DNS Cache

  The cache component (CDndCache) stores cached answers from the DNS servers. When

  resolvers send questions to the protocol module, the cache is first checked for

  a matching valid answer. If found, the cached answer is returned to the resolver,

  and no actual queries need to be sent.

@section	scoped_dns	Scoped name resolution architecture

  The answers to a query can be found from different sources at different scope

  levels. This implementation uses three levels:

@li

  the <b>hosts file</b> is a node local scope source.

@li

  the <b>"real" DNS</b> is a global scope source.

@li

  <b>LLMNR</b> is a link local scope source.

  The above order is also the current default order of the sources: first,

  the <b>hosts</b> file is checked, then real DNS and finally, the link local name

  resolution is attempted. The first source to give an answer defines the whole

  answer. Answers from different sources are never mixed.

  A scope level is assigned to all queries that are received. Currently a global

  scope is given to all GetByName and Query requests. The scope level of the

  GetByAddress is the scope level of queried address.

  For a specific query, only sources that have same or smaller scope level are used.

  For example, only LLMNR is used, when GetByAddress to a link local address

  (169.254/16 or fe80::/10) is requested.

  GetByName queries could also have other than global scope. For example,

  it could be agreed that a query for a name ending with ".local" would have a

  link local scope, and thus only LLMNR would be tried for it (the current

  implementation does not have such feature coded).

*/

/**

// The size of the resolver pool. This defines how many simultaneous

// clients (opened RHostResolver's) are served. Note, that this does

// is not set a limit for the total number open RHostResolver's in all

// applications. If there are more than KDndNumResolver RHostResolvers,

// the resolver gateway (res.cpp in the stack) will maintain a queue, and

// assign the service to applications, when resolvers become available

// from the pool.

*/

const TUint KDndNumResolver = 31;

/**

// Special Progress Notifications for the TReplyCallback: query has been sent.

//

// KDnsNotify_QUERY_SENT

// occurs when the DNS query has actually been sent to the

// server (e.g. socket write completes). Normally this occurs

// very fast after DoQueryL(), except when the packet or DNS

// has to activate the "netdial startup". In such case, the

// sending is blocked until the interface becomes available.

*/

const TInt KDnsNotify_QUERY_SENT = 1;

/**

// Special Progress Notifications for the TReplyCallback: DNS server list is available.

//

// KDnsNotify_HAVE_SERVERLIST

// occurs when the DNS has found at least one DNS server

// address. This signal is only returned if MDnsSession::NewQuery

// returned with > 0 (indicating it started interface startup).

*/

const TInt KDnsNotify_HAVE_SERVERLIST = 2;

/**

// The request is using TCP instead of UDP.

//

// KDnsNotify_USING_TCP

// occurs when the DNS decides to use a connected TCP socket

// for the query to the DNS server. This may happen on receipt of

// DNS reply with TC=1 (truncated), or if some configuration setting

// forces the use of TCP.

//

// The expected effect should be to disable the retransmission

// logic of the resolver, because TCP handles it internally.

*/

const TInt KDnsNotify_USING_TCP = 3;

// -- for now, no other notifys --

/**

// Query modifier flag -- KDnsModifier_RD

//

// Used in aFlags parameter of MDnsSession::NewQuery. This controls

// the state of RD (Recursion Desired) bit in the DNS query messages

// generated from for this query. Normally, this is always set.

*/

const TUint32 KDnsModifier_RD = 1;

/**

//

// Set probe flag -- KDnsModifier_PQ

// 

// Set in ProbeServer() to switch off worker assigning for the query.

// If not set, DNS will check if there's already same query assigned

// to some resolver.

//

*/

const TUint32 KDnsModifier_PQ = 2;

/**

// The query session.

//

// The query session is a handle through which the resolver can request

// the DNS protocol module to do queries and return answers to them. The

// use of separatate session concept (instead of having the methods

// directly on MDnsSource) allows resolver to do multiple queries

// in parallel.

//

// The usage is:

//

// @li (1) open a session with MDnsSource::OpenSession

// @li (2) define the domain name using MDnsSession::NewQuery

// @li (3) activate a specific query (type) with MDnsSession::DoQueryL

// @li (3) after the query is complete (MDnsResolver::ReplyCallback),

//		retrieve answers one by one with repeated calls to MDnsSession::DoNext

// @li (4) session can be used for another query with same domain-name (-> 3),

//		or different domain-name (-> 2)

// @li (6) when session is no more needed, it must be released by MDnsSession::Close

//

// The MDnsSession::CancelQuery can be used at any point to cancel

// all activity, that has been started by MDnsSession::DoQueryL.

//

// When a DNS server is required, the query session will select the current

// default server. This choice will not be changed even if the server is not

// responding or is not reachable. It is the duty of the controlling resolver

// to decide when to try another server, if any are available. For this

// purpose, the MDnsSession has the following methods:

//

// @li MDnsSession::PickDefaultServer, reset to default

// @li MDnsSession::PickNewServer, pick next server in list

*/

class MDnsSession

	{

public:

	/**

	// Load new query information to be resolved.

	//

	// Load a new query into session by converting the information from the

	// TNameRecord or TDnsQuery into DNS format. This only loads the name

	// to be queried, it does not define query type or class.

	//

	// For TNameRecord, if the iName field is empty, then iAddr is used to

	// construct a name to be searched (*.in-addr.arpa or .ip6.int).

	//

	// @param aQuery

	//	defines the name or address to be queried. Does not define

	//	the actual query type. This same question may be used for

	//	different query types (for example A and AAAA).

	// @param aServerScope

	//	the scope level of the query. This limits the servers that

	//	are going to be used.

	// @param aFlags

	//	modify the query operation. See KDnsModifier_* symbols.

	//

	// @returns

	// @li	< 0, if load failed (bad query information)

	// @li	= 0, if query initialized (KErrNone)

	*/

	/**

	// Cancel query activity

	//

	// Cancel all (if any) activity caused by a DoQueryL on this session.

	// This makes session usable for a new query, it does not close the

	// session. MDnsResolver::ReplyCallback is disabled and not called

	// (until reactivated by a new DoQueryL).

	*/

	virtual void CancelQuery() = 0;

	/**

	// Activate a query of specified type for the loaded query information.

	//

	// Enables the MDnsResolver::ReplyCallback.

	// @param aRequestTime

	//	the time when resolver received the request that is causing this

	//	query to be asked. The value is mainly used to determine whether

	//	the cached answer is still valid for this request.

	// @param aQType

	//	the actual query to be done. IN class is assumed.

	//

	// @returns

	// @li	< 0, if query cannot be activated

	// @li	= 0, if query processed (KErrNone)

	*/

	virtual TInt DoQueryL(const TTime &aRequestTime, const EDnsQType aQType) = 0;

	/**

	// Retrieve answer RR's from the previous completed reply.

	//

	// @param aReply

	//	the reply buffer that receives the ansver

	// @param aNext

	//	the index of the answer to return. The first answer has the

	//	index == 0.

	//

	// @returns

	// @li	< 0, if no more answers, or some error is detected

	// @li	= 0, if requested answer has been placed into aReply

	*/

	virtual TInt DoNext(TDnsMessageBuf &aReply, TInt aNext) const = 0;

	/**

	// Set current record into error state.

	//

	// @param aError

	//	the error code to set

	// @param aTTL

	//	the lifetime (seconds) for the error to persist

	//	in the cache before it becoming invalid.

	*/

	virtual void DoError(TInt aError, TUint aTTL) = 0;

	/**

	// Choose next server for the session.

	//

	// @returns

	//	@li	TRUE, if a different server could be picked

	//	@li	FALSE, if no different server available

	*/

	virtual TBool PickNewServer() = 0;

	/**

	// Set default server for the session.

	//

	// Reassign the session to the current chosen "best" server

	// (if any).

	//

	// @returns

	//	@li	TRUE, if a server was selected (or still waiting configuration to stabilise)

	//	@li	FALSE, otherwise (no suitable servers at this point).

	*/

	virtual TBool PickDefaultServer() = 0;

	/**

	// Close the session.

	//

	// Release resources associated with the session and

	// make it available for re-use. CancelQuery is done

	// automaticly.

	*/

	virtual void Close() = 0;

	// Return instance ptr of the actual class instance (only for comparisons)

	virtual const void *const Instance() const = 0;

	};

class MDnsResolver

	{

public:

	/**

	// Response callback.

	//

	// After a query has been activated by MDnsSession::DoQueryL,

	// its progress and completion is reported back by a call

	// to this callback function. The callback may also occur

	// during the DoQueryL.

	//

	// A completion is indicated by a result <= 0. Results > 0

	// are intermediate notifications.

	//

	// @param aErr is defined as follows:

	// @li	< 0, query complete result, some error condition

	// @li	= 0, query complete result, success

	// @li	> 0, query progress notification from DNS.

	//	Currently, only two are used: KDnsNotify_QUERY_SENT, notification

	//	that query has been sent, and KDnsNotify_HAVE_SERVERLIST, notification

	//	that DNS provider has some server list available (which could be empty).