// 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:
// dns_sock.h - Domain Name resolver socket
//

#ifndef __DNS_SOCK_H__
#define __DNS_SOCK_H__

/**
@file dns_sock.h
Basic class for sending and receiving DNS protocol packets
@internalComponent	Domain Name Resolver
*/


#include <e32std.h>
class TMsgBuf;
class CDnsSocketWriter;
class TDnsRequest;


class CDnsSocket : public CBase
/**
Manage sending and receiving of DNS protocol packets on a socket

  @internalComponent	Domain Name Resolver

  Class contains the basic control mechanisms for reading and
  writing the socket. A number of send requests (TDnsRequest) can
  be queued into the "system" and they will be processed one
  after another as socket becomes available for a new send.
  At same time, any incoming packets are received and offered
  for processing.
*/
    {
	friend class CDnsSocketWriter;
protected:
	CDnsSocket(TUint aMaxDnsMessage = 0);
	virtual ~CDnsSocket();
	void ConstructL();
	/**
	Open and activate the UDP socket for DNS traffic (unless already done).
	
	The CDnsSocket has private memory for local address and port, which
	both are initialized to unspecified. However, if the
	ActivateSocketL(const TInetAddr &) has been called, then the last
	such call defines the local address and port for this method also.
	The aNetworkId parameter is used to pickup the correct RConnection
 	handle when the EXPLICIT_SOCKET_BINDING option and NON_SEAMLESS_
	BEARER mobility is enabled.
	*/
	void ActivateSocketL(TUint aNetworkId=0);

	/**
	Open and activate the UDP socket for DNS traffic (unless already done).
	
	@param aBind
		defines the local port and addres for the socket. Address
		and port can be unspecified (the default, if nothing is specified).
	*/
	void ActivateSocketL(const TInetAddr &aBind);
	/**
	Open and activate the TCP listen socket for DNS traffic.
	
	@param aBind
		defines the local port and addres for the socket. Address
		and port can be unspecified (the default, if nothing is specified).
	*/
	void ActivateListenL(const TInetAddr &aBind, TInt aTTL);
	// Close and deactivate the UDP socket for DNS traffic
	void DeactivateSocket(TInt aReason = KErrCancel);
	void SetHoplimit(const TInt aTTL);
	/**
	(Re)Queue the request for processing.
	
	@param aRequest to be queued
	@param aId of the request, if >= 0. If < 0, then a new random ID is generated
	*/
	void Queue(TDnsRequest &aRequest, const TInt aId = -1);
	/**
	(Re)Queue the request for processing.
	
	@param aRequest to be queued
	@param aSocket identifies a specific active socket within the
			CDnsSocket to be used (see CDnsSocket::Query).
	@param aId of the request, if >= 0. If < 0, then a new random ID is generated
	@return
		@li KErrNone, if queued successfully,
		@li KErrNotFound, if the socket does not exist (not queued)
	*/
	TInt Queue(TDnsRequest &aRequest, const RSocket &aSocket, const TInt aId = -1);
	/**
	(Re)Queue the request for processing using connected socket (TCP)
	
	@param aRequest to be queued
	@param aServer The address and port of the DNS server
	@param aId of the request, if >= 0. If < 0, then a new random ID is generated
	@param aTTL of the connection (= -1, the default, requests the system default)
	
	@return KErrNone, if queued successfully, or error code if failed.
	*/
	TInt Queue(TDnsRequest &aRequest, const TInetAddr &aServer, const TInt aId = -1, const TInt aTTL = -1);
	/**
	Reque the request for a resend with same ID (if was queued).
	
	If the request is not already queued, action defaults to
	normal Queue().
	
	Exceptionally, the request assigns new ID when an incomplete query name
	is iterated to apply multiple domain suffices on the interface being used for sending requests
	
	@param aRequest to be queued
	@param aRetryWithSuffix	flag set to identify retry requests on incomplete query names. Defaulted to FALSE
	*/
	void ReSend(TDnsRequest &aRequest, TBool aRetryWithSuffix = EFalse);

	/**
	Received a Query or unmatched Reply packet
	
	The Query method must be implemented by the derived class. The
	Query is called when a DNS protocol message containing a query
	or a reply which is not accepted by any of the current requests,
	is received.
	
	@param aBuf		the received message
	@param aServer	from which the messsage came
	@parma aSocket
		identify originating socket. Note that this
		"const", you cannot do any socket oprartions with
		this. It is only provided for the special Queue
		function, which queues a request to a specific
		socket.
	*/
	virtual void Query(const TMsgBuf &aBuf, const TInetAddr &aServer, const RSocket &aSocket) = 0;
	/**
	Communication error with a destination

    The Error method can be implemented by the derived class. The
	Error is called when DNS socket receives an ICMP error notification
	when communicating with this target.

	@param aServer for which the error relates
	@param the error from the socket
	*/
	virtual void Error(const TInetAddr &aServer, TInt aError) { (void)aServer; (void)aError; };

private:
	TInt AddSecondaryWriter(CDnsSocketWriter *aWriter);
	void DeleteWriter(CDnsSocketWriter *aWriter, TInt aReason);
	CDnsSocketWriter *iWriter;	//< Primary Socket Reader/Writer
protected:
	const TUint iMaxDnsMessage;	//< Max DNS message length.
	/**
	Get the primary RSocket
	
	@return a reference to primary RSocket (UDP)
	*/
	RSocket& Socket();
	TBool IsOpened() const;

	RSocketServ iSS;			//< Keep own Socket Server Session
	RSocket iListener;			//< Used for listening incoming TCP connections, if enabled.
	TUint iConnected:1;			//< = 1, if Socket Server Session is connected.
	TUint iListening:1;			//< = 1, if iListener is open

private:
	TUint iNetworkId;           		//< = network id fetched from the request
	};

class TDnsRequestLink : public TDblQueLink
/**
Link field of requests.

This object is ONLY used as a member of TDnsRequest to maintain
the links when the request is queued for processing.
*/
	{
	friend class TDnsRequest;
	friend class CDnsSocketWriter;
public:
	inline TDnsRequestLink() : iWriter(NULL) {}
	// @return TRUE, if request is currently queued
	inline TBool IsQueued() const { return iWriter != NULL; }
private:
	// @return The current socket object, or NULL if not queued
	inline CDnsSocketWriter *Writer() { return iWriter; }
	/**
	Set new DNS socket object.
	@param	aWriter	The new socket object
	*/
	inline void SetWriter(CDnsSocketWriter *aWriter) { iWriter = aWriter; }
	/**
	Identifies the queued status and handler for the request.
	@li == NULL,
		when the request is not queued.
	@li != NULL,
		a pointer to the internal socket handling object, which
		is currently assigned to handle the request.			
	*/
	CDnsSocketWriter *iWriter;
	};

	
class TDnsRequest
/**
// The base class for the DNS query request.
//
// The request is controlled by three CDnsScoket methods:
//
// @li CDnsSocket::Queue, (re)enter request into CDnsSocket
// @li CDnsSocket::ReSend, (re)enter request into CDnsSocket
// @li CDnsSocket::Remove, remove request from CDnsSocket
//
// While request is "active in the system" (inside CDnsSocket),
// it's state and progress is reported by the following callbacks:
//
// @li TDnsRequest::Build, ready to send a packet
// @li TDnsRequest::Sent, packet sent
// @li TDnsRequest::Reply, possible reply received
// @li TDnsRequest::Abort, request aborted
//
// The main life cycle of a request is as follows:
@verbatim
    .----->.
   /        \
Remove      Queue
 ^           |
 |___        |
 ^   \       V 
 |  ReSend   /
 |      \   /
 |       \ /
 |< - - - |
 |   wait for send
 |     possible
 |< - - - |-------> Build()
 |    send packet
 |     to socket
 |   and wait for
 |    completion
 |< - - - |-------> Sent()
 |        .
 |        .
 |        |
 |   reply matching
 |   the request id
 |     arrives
  < - - - |-------> Reply()

@endverbatim

  In addition to above, at any point in the lifetime, TDnsRequest::Abort()
  could be called, if the request cannot be processed. For example,
  deactivation of the socket will cause Abort call to all requests.

  At any point, the owner of the request can ReSend, Queue or Remove it
  from the system, regardless of the current state of the request. If
  ReSend is called with request that is not already in the system, the
  Queue action happens instead. Remove does nothing, if request is not
  in the system.

  Note that, when a request is queued, it is only a kind of <em>token</em>
  that is placed into queue to wait for its turn on sending socket.
  Nothing about the actual packet to be sent needs to be present, until
  the DnsRequest::Build is called.
*/
	{
	friend class TRequestQueue;
	friend class CDnsSocketWriter;
public:
	/** @brief Build the DNS packet for the request into buffer
	//
	// Build callback occurs just before the socket is ready to send a message
	// corresponding this request. This method should build the desired
	// message into aBuf, determine the actual destination address (aServer)
	// return TRUE (= 1). The DnsSocket will start a socket send for the
	// message. TDnsRequest::Sent will be called, when the socket send
	// operation completes.
	//
	// If message cannot be build (or should not be sent), return FALSE (= 0)
	//
	// In either case, the request will remain queued in DnsSocket (unless
	// removed).
	//
	// Build CAN call CDnsSocket::Remove, even if it returns TRUE (in which
	// case the message will be sent, but there will not be any Sent callback).
	//
	// @param aSource	the dns socket instance owning the request
	// @retval aBuf		the buffer to be initialized (it has already been preinitialized
	//					using the TDndHeader::Init method). Build method can
	//					either ignore this or use it as a base.
	// @retval aServer	must be initialized with the destination address and port
	//					of the message (if return is TRUE). If the request is
	//					using TCP, this is ignored.
	// @param aRecvLength
	//				the current size of the receive buffer
	//
	// @returns
	//	@li	TRUE,	if message and server has been set, and socket should send the
	//				message out, request is moved into "wait" state.
	//	@li	FALSE,	if socket should not send any message from this request. This
	//				causes the request to be moved into "wait" state.
	*/
	virtual TBool Build(CDnsSocket &aSource, TMsgBuf &aBuf, TInetAddr &aServer, TInt aRecvLength) = 0;
	/** @brief A packet has been sent to the server
	//
	// Sent callback occurs when the "send" of the message completes on the socket.
	// This is a notification only. The request remains queued (unless removed).
	//
	// Sent CAN call CDnsSocket::Remove.
	//
	// @param aSource	the dns socket instance owning the request
	*/
	virtual void Sent(CDnsSocket &aSource) = 0;
	/** @brief A reply received
	//
	// Reply callback occurs when a socket receives a DNS reply message from a
	// server with an ID matching this request (in wait state). The Reply
	// method should do some further verifications whether the reply really
	// is for this request.
	// If the reply matches this request, the method should process the reply
	// and return TRUE.
	//
	// If the reply does not match this request, the method should return
	// FALSE, and the DnsSocket will try another request with same id. If
	// there are no requests that match this ID (or if all of them return
	// FALSE, the reply message is offered to the CDnsSocket::Query method).
	//
	// In either return (TRUE or FALSE), the request will remain in "wait" state
	// and queued in DnsSocket (unless removed).
	//
	// Reply CAN call CDnsSocket::Remove, and still return either
	// TRUE or FALSE.
	//
	// @param aSource	the dns socket instance owning the request
	// @param aBuf		the buffer containing the received reply.
	// @param aServer	the from address of the reply message
	//
	// @returns
	//	@li	TRUE,	if the reply belongs to this request and has been
	//				processed,
	//	@li	FALSE,	if the reply does not belong to this request, and
	//				some other request should be asked.
	*/
	virtual TBool Reply(CDnsSocket &aSource, const TMsgBuf &aBuf, const TInetAddr &aServer) = 0;
	/** @brief Request aborted
	//
	// Abort callback occurs when the DNS socket throws out a request
	// that it has queued. This is NOT called, when the request is
	// removed explicitly by CDnsSocket::Remove. The normal reason
	// for Abort is CDnsSocket::DeactivateSocket, if called with
	// queued requests present.
	//
	// There is no reason for Abort to call CDnsSocket::Remove,
	// because the request has already been effectively removed
	// before the Abort call.
	//
	// @param aSource	the dns socket instance owning the request
	// @param aReason	the reason code for the abort
	*/
	virtual void Abort(CDnsSocket &aSource, const TInt aReason) = 0;
	// Return TRUE, if request is queued
	inline TBool IsQueued() const { return iQueueLink.IsQueued(); }
	// Cancel request (silently remove from the queue, if any)
	void Cancel();
	// Return ID value
	TInt Id() const { return iId; }
private:
	TDnsRequestLink iQueueLink;	//< Linking requests together
	TUint16 iId;				//< The assigned request ID
	};
#endif