// Copyright (c) 2000-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:
// Purpose:		Definition of CUrl class - Url processor based on RFC2396.
// CUrl encapsulates a url and provides access to its components. On creation, the contents of 
// the url is in unescaped mode - excluded characters (as defined by RFC2396) have not been coded into their 
// escape triples. Two NewL() functions are provided. The first takes any descriptor and encapsulates it into
// the CUrl object, and leaves if the the url begins with a ':' (EWapErrCorruptUrl) or if the scheme is 
// 
//

//				corrupted (EWapErrCorruptScheme). The second NewL() creates a url with a file scheme (file://) from a 
//				TParseBase argument, and will leave if the url is invalid (EWapErrCorruptUrl). Two static functions have 
//				been provided that each take a descriptor argument which is then escape encoded/decoded.
//
//				NOTE - maintainer needs detailed knowledge of url parsing (RFC2396)
//

#if !defined(__URLBASE_H__)
#define __URLBASE_H__

// System includes
//
#include <e32base.h>
#include <f32file.h>
#include <wapengstd.h>


// Definition of CUrl
//
class CUrl : public CBase
	{
public:	// Type definitions

	//	Enum of component parts of the Url.
	//
	enum TComponent
		{	
		EUrlScheme = 0x01,
		EUrlLocation = 0x02,
		EUrlPath = 0x04,
		EUrlQuery = 0x08,
		EUrlFragment = 0x10,
		EUrlFileName = 0x20, // the end of the path
		EUrlUsername = 0x40,
		EUrlPassword = 0x80,
		EUrlAuthority = EUrlLocation | EUrlUsername | EUrlPassword,
		EUrlNoCredentials = EUrlScheme | EUrlLocation | EUrlPath | EUrlQuery |
			EUrlFragment,
		EUrlGenericCompare = EUrlScheme | EUrlAuthority | EUrlPath | EUrlQuery
		};

public:	// Methods

	// Static factory c'tor. Creates a CUrl object from a
	// descriptor. This can hold any kind of Url - local file or http,
	// full url with scheme, or a relative url. Leaves if scheme is
	// corrupted or url is invalid.
	//
	// In:
	// aUrl	- descriptor of URL
	//
	// Rtn: pointer to created CUrl object
	//
	IMPORT_C static CUrl* NewL(const TDesC& aUrl);

	// Static factory c'tor. Creates a CUrl objects from a TParseBase
	// that refers to a file in the local file system.  This function
	// will prefix path with file scheme - file://. Leaves if url is
	// invalid.
	//
	// In:
	// aFileName	- path for a resource in local file system
	//
	// Rtn: pointer to created CUrl object
	//
	IMPORT_C static CUrl* NewL(const TParseBase& aFileName);

	// Resolves aRelativeUrl against aBaseUrl based on relative
	// parsing algorithm in RFC2396. Resolved url is returned Note -
	// if aBaseUrl is empty, the relative url aRelativeUrl is
	// returned.
	//
	// In:
	// aBaseUrl		- base url to resolve against
	// aRelativeUrl	- relative url
	//
	// Rtn: resolved url - owner is transfered to caller
	//
	IMPORT_C static CUrl* ResolveL(CUrl& aBaseUrl, CUrl& aRelativeUrl);

	// Sets current url to aUrl. If leave occurs, this object is unchanged.
	//
	// In:
	// aUrl	- the new url
	//
	IMPORT_C void SetL(CUrl& aUrl);

	// Returns a copy of itself.
	//
	// Rtn: copy of itself - ownership transfered to caller.
	//
	IMPORT_C CUrl* AllocL() const;

	// Returns a copy of one of its components.Currently any defined value of component
	// is supported, but the result may well not be a valid URL.
	//
	// In:
	// aComponent	- the desired component of the url
	//
	// Rtn: copy of the desired url component - ownership is transfered to caller.
	//
	IMPORT_C CUrl* AllocL(TComponent aComponent) const;

	// Returns a TPtrC to the specified component part of tbe Url.
	//
	// In:
	// aType	- the desired component of the url.
	//
	// Rtn: pointer to the component in the url
	//
	IMPORT_C virtual const TPtrC Component(TComponent aType) const;

	// Sets the specified component to the specified value. This function is not completely 
	// implemented - currently it will work in the following circumstances;
	// 1 - the desired component already exists in the URL 
	// 2 - it's the username or password and the location exists. 
	// In other cases the function will leave with KErrNotSupported.
	// 
	// In:
	// aComponent	- the component to be set.
	// aValue		- the new value. NB must already be escaped.
	//
	IMPORT_C void SetComponentL(TComponent aComponent, const TDesC& aValue);

	// Overloaded equality operator.
	//
	// In:
	// aUrl	- the Url to be compared against.
	//
	// Rtn: ETrue is returned if aUrl is the same as this url.
	//
	IMPORT_C TBool operator==(CUrl& aUrl) const;	

	// Compares the specified component part of two urls. 
	//
	// In:
	// aUrl				- the url to be compared against.
	// aCompareComps	- the component of the urls to be compared. Defaults to components defined by EUrlGenericCompare.
	//
	// Rtn: zero is returned for an exact match.
	//
	IMPORT_C TInt Compare(CUrl& aUrl, TInt aCompareComps = EUrlGenericCompare) const;

	// Returns TDesC to descriptor of entire url.
	//
	// Rtn: the descriptor to the url.
	//
	inline const TDesC& UrlDes() const;

	// THIS SHOULD NOT BE USED AS CAUSES PANIC - WILL BE REMOVED.
	//
	IMPORT_C CUrl* UrlEscapedL() const;

	// THIS SHOULD NOT BE USED AS CAUSES - WILL BE REMOVED.
	//
	IMPORT_C CUrl* UrlUnescapedL() const;

	// D'tor
	//
	IMPORT_C ~CUrl();

	// Encodes any excluded characters in input string as escape triples. Uses the overloaded
	// function.
	//
	// THIS SHOULD NOT BE USED - WILL BE REMOVED. USE NEW OVERLOAD FUNCTION.
	//
	// In:
	// aString	- descriptor with string to be encoded.
	//
	// Rtn: version of string with excluded characters converted to
	// escape triples - ownership transfered to caller.
	//
	IMPORT_C static HBufC* EscapeEncodeL(const TDesC& aString);

	// Encodes any excluded characters in input string as escape triples. The excluded characters
	// are set by the value or aEscapeMode. Control characters, space (ASCII 0x20) and characters
	// above 127 are always encoded as escape triples.
	//
	// In:
	// aString		- descriptor with string to be encoded.
	// aEscapeMode	- governs which chars are to excluded (and escaped)
	//
	// Rtn: version of string with excluded characters converted to
	// escape triples - ownership transfered to caller.
	//
	IMPORT_C static HBufC* EscapeEncodeL(const TDesC& aString, TInt aEscapeMode);

	// Decodes any escape triples in input string into original
	// excluded characters.
	//
	// In:
	// aString	- descriptor with string to be decoded.
	//
	// Rtn: version of string with escape triples converted back to
	// excluded characters - ownership transfered to caller.
	//
	IMPORT_C static HBufC* EscapeDecodeL(const TDesC& aString);

	// Convert a Unicode string into UTF8 format.
	// 
	// In:
	// aString	- the input Unicode string.
	//
	// Rtn: the converted string (UTF8 format) - ownership transfered to caller.
	//
	IMPORT_C static HBufC8* ConvertFromUnicodeToUtf8L(const TDesC& aString);

	// Convert a UTF8 string into Unicode format.
	// 
	// In:
	// aString	- the input UTF8 string.
	//
	// Rtn: the converted string (Unicode format) - ownership transfered to caller.
	//
	IMPORT_C static HBufC* ConvertToUnicodeFromUtf8L(const TDesC8& aString);

private:	// Type definitions

	// Helper class used to resolve a relative path against a base path.
	//
	class TRelativePaths;

	// Enumeration of panic codes for this class
	//
	enum TPanicCode
	{
	EInvalidUrl
	};

private:	// Methods

	// Normal c'tor - non-allocating creation of this class
	//
	CUrl();

	// Second-phase c'tor for general url - any allocation takes place here.
	//
	// In:
	// aUrl	- descriptor containing url.
	//
	void ConstructL(const TDesC& aUrl);

	// Second-phase c'tor for url with file scheme - any allocation
	// takes place here.
	//
	// In:
	// aFileName	- path to local file system resource.
	//
	void ConstructL(const TParseBase& aFileName);

	// Panic handler for ths class - kills the process in the event of
	// a panic
	//
	// In:
	// aPanicCode	- code enumerating the panic that has occured.
	//
	void Panic(TPanicCode aPanicCode) const;

	// Checks the scheme if present to ensure it is valid
	// Leaves with EWapErrCorruptScheme if not valid
	//
	// In:
	// aScheme - the scheme to be checked
	//
	void CheckSchemeValidL(const TDesC& aScheme) const;

	// Parses a url to find the start and end of a specified component
	// in the url.
	//
	// In:
	// aComponent	- the component sought.
	// aUrl			- descriptor of url to be parsed
	//
	// Out:
	// aStartPos - index of start of component; is KCUrlInvalidCharPos
	// if component not found.
	// aEndPos - index of end of component; is KCUrlInvalidCharPos if
	// component not found.
	//
	void Part(TComponent aComponent, const TDesC& aUrl, TInt& aStartPos, 
			  TInt& aEndPos) const;

	// Parses an identified authority to extract the location,
	// username or password.
	//
	// In:
	// aComponent - the component sought. (EUrlLocation, EUrlUsername
	// 										or EUrlPassword)
	// aUrl			- descriptor of url to be parsed
	//
	// In/Out:
	// aStartPos - index of start of component; is KCUrlInvalidCharPos
	// if component not found. Is the start of the authority on inupt.
	// aEndPos - index of end of component; is KCUrlInvalidCharPos if
	// component not found. End of authority on input.
	void PartOfAuthority(TComponent aComponent, const TDesC& aUrl, 
						 TInt& aStartPos, TInt& aEndPos) const;

private:	// Attributes

	// Pointer to buffer containing url. Owned by this class
	//
	HBufC*	iUrlDes;
	};

inline const TDesC& CUrl::UrlDes() const
//
//	Return descriptor to url
	{
	return *iUrlDes;
	}

class CUrl::TRelativePaths
//
//	Helper class used to resolve a relative path against a base path
	{
public:	// Methods

	// Normal c'tor
	//
	// In:
	// aBasePath		- base path to resolve against
	// aRelativePath	- relative path
	// aResolvedPath	- result of resolving relative path against base path
	//
	TRelativePaths(TPtrC aBasePath, TPtrC aRelativePath, TPtr aResolvedPath);

	// Does the path resolution
	//
	void ResolveRelativePaths();

	// Cleans resolved path, removing structures such as '/../'
	//
	void CleanResolvedPath();

public:	//	Attributes

	// Descriptor for base path
	//
	TPtrC iBasePath;

	// Descriptor for relative path
	//  
	TPtrC iRelativePath;

	// Modifiable descriptor to resolved path
	//
	TPtr iResolvedPath;
	};

#endif // __URLBASE_H__