/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of the License "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: 

 * Implementation of an attribute type and a value, as defined by the X.520 standard

 *

 */

 /**

  @file 

  @publishedAll

  @released

 */

 #if !defined(__X520AVA_H__)

 #define __X520AVA_H__

 #include <e32base.h>

 #include <e32std.h>

 #include <s32std.h>

 //these are for internal use only

 //these are the only attribute types we handle at present

 _LIT(KX520CountryName,"2.5.4.6");

 _LIT(KX520OrganizationName,"2.5.4.10");

 _LIT(KX520OrganizationalUnitName,"2.5.4.11");

 _LIT(KX520LocalityName,"2.5.4.7");

 _LIT(KX520StateOrProvinceName,"2.5.4.8");

 _LIT(KX520Title,"2.5.4.12");

 _LIT(KX520CommonName,"2.5.4.3");

 _LIT(KX520GivenName,"2.5.4.42");

 _LIT(KX520Surname,"2.5.4.4");

 _LIT(KX520Initials,"2.5.4.43");

 _LIT(KX520GenerationQualifier,"2.5.4.44");

 _LIT(KX520DNQualifier,"2.5.4.46");

 _LIT(KX520SerialNumber,"2.5.4.5");

 _LIT(KX520Description,"2.5.4.13");

 //more attribute types we handle at present

 _LIT(KX520PostalCode,"2.5.4.17");

 _LIT(KRFC2247DomainComponent, "0.9.2342.19200300.100.1.25");

 _LIT(KRFC2256Street,"2.5.4.9");

 _LIT(KPKCS9UnstructuredName, "1.2.840.113549.1.9.2");

 //email address is deprecated but we support it anyway...

 _LIT(KPKCS9EmailAddress, "1.2.840.113549.1.9.1");

 /** The maximum length allowed for a country name. */

 const TInt KX520MaxCLength = 2;

 /** The maximum length allowed for an organization name. */

 const TInt KX520MaxOLength = 64;

 /** The maximum length allowed for an organizational unit name. */

 const TInt KX520MaxOULength = 64;

 /** The maximum length allowed for a locality name. */

 const TInt KX520MaxLLength = 128;

 /** The maximum length allowed for a state or province name. */

 const TInt KX520MaxSOPLength = 128;

 /** The maximum length allowed for an title. */

 const TInt KX520MaxTLength = 64;

 /** The maximum length allowed for a common name. */

 const TInt KX520MaxCNLength = 256;

 /** The maximum length allowed for a given name. */

 const TInt KX520MaxGNLength = 16;

 /** The maximum length allowed for a surname. */

 const TInt KX520MaxSLength = 40;

 /** The maximum length allowed for initials. */

 const TInt KX520MaxILength = 5;

 /** The maximum length allowed for a generation qualifier. */

 const TInt KX520MaxGQLength = 3;

 /** The maximum length allowed for a serial number. */

 const TInt KX520MaxSNLength = 64;

 /** The maximum length allowed for a postal code. */

 const TInt KX520MaxPostalCodeLength = 40;

 /** The maximum length allowed for an email address. */

 const TInt KPKCS9MaxEmailAddressLength = 256;

 /** The maximum length allowed for an unstructured name. */

 const TInt KPKCS9MaxUnstructuredNameLength = 256;

 // No maximum was specified in the standard - 128 should be sufficient

 /** The maximum length allowed for an RFC 2247 domain component. 

 * 

 * Each component of the domain name is a short string. */

 const TInt KRFC2247MaxDomainComponentLength = 128;

 /** The maximum length allowed a for street. */

 const TInt KRFC2256StreetLength = 128;

 /** The maximum length allowed for an Description field. */

 const TInt KX520MaxDescriptionLength = 1024;

 /** The attribute type. 

 * 

 * @since v6.0 */

 enum TAttributeType

 	{

 	/** A common name */

 	ECommonName,

 	/** A locality name */

 	ELocalityName,

 	/** A state or province name */

 	EStateOrProvinceName,

 	/** An organization name */

 	EOrganizationName,

 	/** An organizational unit name */

 	EOrganizationalUnitName,

 	/** A title */

 	ETitle,

 	/** A qualifier */

 	EDNQualifier,

 	/** The name of a country */

 	ECountryName,

 	/** A given name */

 	EGivenName,

 	/** A surname */

 	ESurname,

 	/** Initials */

 	EInitials,

 	/** A generation qualifier */

 	EGenerationQualifier,

 	/** An email address. This is deprecated. */

 	EPKCS9EmailAddress,

 	/** A postal code */

 	EPostalCode,

 	/** A serial number */

 	ESerialNumber,

 	/** An RFC 2247 domain component.

 	* 

 	* A domain name is made up of an ordered set of components.*/

 	ERFC2247DomainComponent,

 	/** RFC 2256 street component.

 	* 

 	* A street */

 	ERFC2256Street,

 	/** A name of the subject of a certificate as an unstructured ASCII string */

 	EPKCS9UnstructuredName,

 	/** A Description */

 	EX520Description,

 	};

 class CASN1EncSequence;

 class CX520AttributeTypeAndValue : public CBase

 /** Contains an attribute type and a value, as defined by the X.520 standard.

 * 

 * A Distinguished Name object, as defined by the X.500 standard, consists of 

 * a sequence of these objects. 

 * 

 * @since v6.0 

 */

 // Attribute and value pair class. Attribute and value pairs 

 //	are used in distinguished names and certificate attributes. 

 //	Stores data in ASN.1 format internally.

 	{

 public:

 	// Constructs a new object from ASN.1-encoded DER binary data

 	/** Creates a new CX520AttributeTypeAndValue object from the specified buffer containing 

 	* the encoded binary representation.

 	* 

 	* Initialises the object from its encoded binary form into an internal representation.	

 	* 

 	* @param aBinaryData	The encoded binary representation.

 	* @return				The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewL(const TDesC8& aBinaryData);

 	// Constructs a new object from ASN.1-encoded DER binary data

 	/** Creates a new CX520AttributeTypeAndValue object from the specified buffer containing 

 	* the encoded binary representation, and puts a pointer to the new object onto 

 	* the cleanup stack.

 	* 

 	* Initialises the object from its encoded binary form into an internal representation.	

 	* 

 	* @param aBinaryData	The encoded binary representation.

 	* @return				The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewLC(const TDesC8& aBinaryData);

 	// Constructs a new object from ASN.1-encoded DER binary data

 	/** Creates a new CX520AttributeTypeAndValue object from the specified buffer containing 

 	* the encoded binary representation, starting at the specified offset.

 	* 

 	* Initialises the object from its encoded binary form into an internal representation.

 	* 

 	* @param aBinaryData	The encoded binary representation.

 	* @param aPos			The offset position from which to start decoding.

 	* @return				The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewL(const TDesC8& aBinaryData, TInt& aPos);

 	// Constructs a new object from ASN.1-encoded DER binary data

 	/** Creates a new CX520AttributeTypeAndValue object from the specified buffer containing 

 	* the encoded binary representation, starting at the specified offset, and puts 

 	* a pointer to the new object onto the cleanup stack.

 	* 

 	* Initialises the object from its encoded binary form into an internal representation.

 	* 

 	* @param aBinaryData	The encoded binary representation.

 	* @param aPos			The offset position from which to start decoding.

 	* @return				The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewLC(const TDesC8& aBinaryData, TInt& aPos);

 	/** Creates a new CX520AttributeTypeAndValue object from an existing object.

 	* 

 	* This is equivalent to a copy constructor.

 	* 

 	* @param aPair	The CX520AttributeTypeAndValue object.

 	* @return		The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewL(const CX520AttributeTypeAndValue& aPair);

 	/** Creates a new CX520AttributeTypeAndValue object from an existing object, and 

 	* puts a pointer to the new object onto the cleanup stack.

 	* 

 	* This is equivalent to a copy constructor.

 	* 

 	* @param aPair	The CX520AttributeTypeAndValue object.

 	* @return		The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewLC(const CX520AttributeTypeAndValue& aPair);

 	/** Creates a new CX520AttributeTypeAndValue object from the specified read stream.

 	* 

 	* @param aStream	Stream from which the object is to be internalised.

 	* @return			The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewL(RReadStream& aStream);

 	/** Creates a new CX520AttributeTypeAndValue object from the specified read stream, 

 	* and puts a pointer to the new object onto the cleanup stack.

 	* 

 	* @param aStream	Stream from which the object is to be internalised.

 	* @return			The new CX520AttributeTypeAndValue object. */

 	IMPORT_C static CX520AttributeTypeAndValue* NewLC(RReadStream& aStream);

 	/** Creates a new CX520AttributeTypeAndValue object from an attribute type and value.

 	* 

 	* @param aType	Attribute type

 	* @param aValue	Attribute value

 	* @return		New CX520AttributeTypeAndValue object */

 	IMPORT_C static CX520AttributeTypeAndValue* NewL(TAttributeType aType, const TDesC8& aValue);

 	/** Creates a new CX520AttributeTypeAndValue object from an attribute type and value.

 	* 

 	* @param aType	Attribute type

 	* @param aValue Attribute value

 	* @return		New CX520AttributeTypeAndValue object on the cleanup stack */

 	IMPORT_C static CX520AttributeTypeAndValue* NewLC(TAttributeType aType, const TDesC8& aValue);

 	/** Destructor.

 	* 

 	* Frees all resources owned by the object, prior to its destruction. */

 	IMPORT_C ~CX520AttributeTypeAndValue();

 	/** Gets the encoded attribute type of the object.

 	* 

 	* @return	A pointer descriptor representing the encoded attribute type. */

 	IMPORT_C const TPtrC Type() const;

 	/** Gets the encoded attribute value of the object.

 	* 

 	* @return	The pointer descriptor representing the encoded attribute value. */

 	IMPORT_C const TPtrC8 EncodedValue() const;

 	// Creates a copy of object's ASN.1 DER encoding.

 	// @return	New buffer containing object's ASN.1 DER encoding.

 	/** Gets the decoded value.

 	* 

 	* @return	A heap descriptor containing the decoded value. */

 	IMPORT_C virtual HBufC* ValueL() const;

 	/** Encodes the contents into an ASN.1 sequence object.

 	* 

 	* This is useful to insert attribute type/value pairs into other ASN.1 

 	* encoding trees.

 	* 

 	* @return	New ASN.1 sequence object containing attribute 

 	* 			type/value pair in for of an OID and an octet string; 

 	*			leaves the returned object on the cleanup stack. */

 	IMPORT_C CASN1EncSequence* EncodeASN1LC() const;

 	/** Encodes the contents into an ASN.1 sequence object.

 	* 

 	* Useful to insert attribute type/value pairs into other ASN.1 

 	* encoding trees.

 	* 

 	* @return 	New ASN.1 sequence object containing attribute 

 	* 			type/value pair in for of an OID and an octet string. */

 	IMPORT_C CASN1EncSequence* EncodeASN1L() const;

 	// This function compares the current element with aElement.

 	/** Compares the attribute type and decoded value of the specified object.

 	* 

 	* @param aElement	The CX520AttributeTypeAndValue object to be compared.

 	* @return 			ETrue, if the attribute types and the decoded values match; 

 	* 					EFalse, otherwise. */

 	IMPORT_C virtual TBool ExactMatchL(const CX520AttributeTypeAndValue& 

 		aElement) const;

 	/** Externalises an object of this class to a write stream.

 	* 

 	* The presence of this function means that the standard templated operator<<() 

 	* can be used to externalise objects of this class.

 	* 

 	* @param aStream	Stream to which the object should be externalised. */

 	virtual void ExternalizeL(RWriteStream& aStream) const;

 private:

 	virtual void InternalizeL(RReadStream& aStream);

 	CX520AttributeTypeAndValue(const TAttributeType aType);

 	CX520AttributeTypeAndValue(); ///< Protected default constructor

 	void ConstructL(const CX520AttributeTypeAndValue& aPair);

 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);

 	void ConstructL(TAttributeType aType, const TDesC8& aValue);

 	/**

      * This method finds out if case-insensitive comparisons must be done or not.

 	 * Email Address is the exceptional case of 'IA5String' value type for which comparisons must be

 	 * done case-insensitivly.

 	 * 

 	 * @param aSource	contains the encoded value of the attribute type.

  	 * @return	    	ETrue, if case-insensitive comparisons are to be done. 

 	 * 		        	This is only when value type is a Printable String OR if attribute type is an Email Address. 

 	 * 		        	EFalse, otherwise.

  	 */ 

  	TBool IsCaseInSensitiveL(const TDesC8& aSource) const;

 	HBufC* iType; ///< The encoded type

 	HBufC8* iValue; ///< The encoded value

 	};

 #endif