cryptoservices/certificateandkeymgmt/inc/x500dn.h
changeset 8 35751d3474b7
parent 0 2c201484c85f
--- a/cryptoservices/certificateandkeymgmt/inc/x500dn.h	Tue Jul 21 01:04:32 2009 +0100
+++ b/cryptoservices/certificateandkeymgmt/inc/x500dn.h	Thu Sep 10 14:01:51 2009 +0300
@@ -1,282 +1,280 @@
-/*
-* 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 the class that holds the Distinguished Name of a subject
-*
-*/
-
-
-
-
-/**
- @file 
- @publishedAll
- @released
-*/
-#if !defined (__X500DN_H__)
-#define __X500DN_H__
-
-#include <e32base.h>
-#include <e32std.h>
-#include <s32file.h>
-#include <x520ava.h>
-
-class CX500DistinguishedName : public CBase
-/** Holds the Distinguished Name of a subject.
-*
-* A collection of 'attribute type and value' objects, as defined by the X.520 
-* standard.
-*
-* The name used in X.509 certificates is the X.500 Distinguished Name, which 
-* describes a path through an X.500 Directory Information Tree.
-*
-* A Distinguished Name is a series of name-value pairs that uniquely identify 
-* an entity, i.e. the certificate subject. 
-*
-* @publishedAll
-* @released
-*
-* <!-- 
-* This is necessary when working with certificates, certificate requests, directories, etc. 
-* -->
-*/
-	{
-public:
-	/** Creates a new Distinguished Name object from the specified buffer containing 
-	* the encoded binary representation, starting at the specified offset.
-	* 
-	* @param aBinaryData	The encoded binary representation.
-	* @param aPos			The position from which to start decoding.
-	* @return				The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData, TInt& aPos);
-	
-	/** Creates a new Distinguished Name object from the specified buffer containing 
-	* the encoded binary representation, starting at the specified offset, and puts 
-	* a pointer to it onto the cleanup stack.
-	* 
-	* @param aBinaryData	The encoded binary representation.
-	* @param aPos			The position from which to start decoding.
-	* @return				The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData, TInt& aPos);
-	
-	/** Creates a new Distinguished Name 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 Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData);
-	
-	/** Creates a new Distinguished Name object from the specified buffer containing 
-	* the encoded binary representation, and puts a pointer to it 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 Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData);
-	
-	/** Creates a new Distinguished Name object from the specified read stream.
-	* 
-	* Construction is from a stream.
-	* 
-	* @param aStream	Stream from which the contents should be internalised.
-	* @return			The newDistinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewL(RReadStream& aStream);
-	
-	/** Creates a new Distinguished Name object from the specified read stream, and 
-	* puts a pointer to it onto the cleanup stack.
-	* 
-	* @param aStream	Stream from which the contents should be internalised.
-	* @return			The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewLC(RReadStream& aStream);	
-	
-	/** Creates a new Distinguished Name object from the specified array of 'attribute 
-	* type and value' objects.
-	* 
-	* The elements of the specified array are copied into this object.
-	* 
-	* @param aElements	The array of 'attribute type and value' objects to be copied.
-	* @return			The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
-	
-	/** Creates a new Distinguished Name object from the specified array of 'attribute 
-	* type and value' objects, and puts a pointer to it onto the cleanup stack.
-	* 
-	* The elements of the specified array are copied into this object.
-	* 
-	* @param aElements	The array of 'attribute type and value' objects to be copied.
-	* @return			The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewLC(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);	
-	
-	/** Creates a new Distinguished Name object from an existing object.
-	* 
-	* This is equivalent to a copy constructor.
-	* 
-	* @param aName	The Distinguished Name object to be copied.
-	* @return		The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewL(const CX500DistinguishedName& aName);
-	
-	/** Creates a new Distinguished Name object from an existing object, and puts a 
-	* pointer to it onto the cleanup stack.
-	* 
-	* This is equivalent to a copy constructor.
-	* 
-	* @param aName	The Distinguished Name object to be copied.
-	* @return		The new Distinguished Name object. */
-	IMPORT_C static CX500DistinguishedName* NewLC(const CX500DistinguishedName& aName);
-	
-	/** 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. */
-	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
-	
-	/** Gets the number of 'attribute type and value' objects contained by this Distinguished 
-	* Name object.
-	* 
-	* @return	The number of 'attribute type and value' objects. */
-	IMPORT_C TInt Count() const;
-	
-	/** Gets a reference to specific 'attribute type and value' object as identified 
-	* by the specified index.
-	* 
-	* @param aIndex	The index number identifying the specific 'attribute type and 
-	* 				value' object. This number is relative to zero. This value must be non-negative 
-	* 				and less than the number of objects currently contained by this Distinguished 
-	* 				Name object.
-	* @return		The referenced 'attribute type and value' object. */
-	IMPORT_C const CX520AttributeTypeAndValue& Element(TInt aIndex) const;
-	
-	/** Destructor.
-	* 
-	* Frees all resources owned by the object, prior to its destruction. */
-	IMPORT_C ~CX500DistinguishedName(); 
-
-	/** Compares the specified Distinguished Name object with this Distinguished Name 
-	* object.
-	* 
-	* @param aName	The Distinguished Name object to be compared.
-	* @return		ETrue, if the Distinguished Name objects contain exactly the same 'attribute 
-	* 				type and value' objects; EFalse, otherwise.
-	* @see CX520AttributeTypeAndValue::ExactMatchL() 
-	*
-	* <!--	This function checks if all the fields of aName and 
-	*		iElements are the same but not necessarily in the same order. -->
-	*/
-	IMPORT_C TBool ExactMatchL(const CX500DistinguishedName& aName) const;
-
-	/** <!--
-	 // This function checks if the elements of iElements are a superset of
-	 // the fields in aName.
-	 // @param aName We want to check that the fields in aName are present in iElements.
-	 // @return 
-	 // <UL>
-	 // <LI>ETrue if all the fields in aName have a corresponding field in iElements.</LI>
-	 // <LI>EFalse otherwise</LI>
-	 // </UL>
-	 -->
-	* Tests whether all 'attribute type and value' objects contained in the specified 
-	* Distinguished Name object are also contained within this Distinguished Name object.
-	* 
-	* This function checks if the elements of iElements are a superset of the fields in aName.
-	* 
-	* @param aName	The Distinguished Name object to be compared.
-	* @return		ETrue, if all 'attribute type and value' objects contained in the specified 
-	* 				Distinguished Name object are also contained within this Distinguished Name 
-	* 				object; EFalse, otherwise. */
-	IMPORT_C TBool IsWithinSubtreeL(const CX500DistinguishedName& aName) const;
-
-	/** <!--
-	 // This function compares each of the elements in iElements with aElement. The comparison
-	 // is made by the CX520AttributeTypeAndValue::ExactMatchL function.
-	 // @param aElement The element which we want to compare the elements of iElements with.
-	 // @return 
-	 // <UL>
-	 // <LI>ETrue if one of the elements in iElements is equal to aElement.</LI>
-	 // <LI>EFalse otherwise</LI>
-	 // </UL>
-	 -->
-	* Tests whether this Distinguished Name object contains the specified 'attribute 
-	* type and value' object.
-	* 
-	* This function compares each of the elements in iElements with aElement. The comparison
-	* is made by the CX520AttributeTypeAndValue::ExactMatchL() function.
-	* 
-	* @param aElement	The 'attribute type and value' object to be checked.
-	* @return			ETrue, if the specified 'attribute type and value' object is contained 
-	* 					in this Distinguished Name object; EFalse otherwise. */
-	IMPORT_C TBool MatchElementL(const CX520AttributeTypeAndValue& aElement) const;
-	
-	/** Gets the decoded value associated with the specified field/attribute name, 
-	* from the Distinguished Name.
-	* 
-	* @param aFieldName	The field name.
-	* @return			A heap descriptor containing the decoded value associated with the 
-	* 					specified field name. */
-	IMPORT_C HBufC* ExtractFieldL(const TDesC& aFieldName) const;
-	
-	/** Gets the decoded value for the common or organisation name.
-	* 
-	* @return A heap descriptor containing the decoded value of the common or organisation name. */
-	IMPORT_C HBufC* DisplayNameL() const;
-
-	/** Encodes a DN into an ASN.1 object tree.
-	* 
-	* Note that the tree has the following format:
-	* @code
-    *         SEQUENCE-OF
-    *             SET-OF
-    *                 SEQUENCE-OF
-    *                     OID
-    *                     value (usually OCTET STRING)
-    *             ...
-    * @endcode
-	* 
-	* A SEQUENCE-OF object with a changed tag is used instead of 
-	* a SET-OF object. This should be all right as long as it 
-	* contains only one child, because otherwise child order in 
-	* a SET-OF becomes important.
-	* 
-	* This function does not introduce an additional dependency 
-	* on ASN1 library because X500 library already depends on 
-	* it -- the attribute type/value class stores and manipulated 
-	* ASN.1 encodings as its values.
-	* 	
-	* @return	ASN.1 sequence object containing the DN, 
-	* 			pushed on the cleanup stack.
-	*/
-	IMPORT_C CASN1EncSequence* EncodeASN1LC() const;
-
-	/** Encodes a DN into an ASN.1 object tree. 
-	* 
-	* See note in the description of #EncodeASN1LC for the explanation of 
-	* the resulting encoding tree format.
-	* 	
-	* @return	ASN.1 sequence object containing the DN. */
-	IMPORT_C CASN1EncSequence* EncodeASN1L() const;
-
-private:
-	CX500DistinguishedName();
-	void ConstructL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
-	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
-	void ConstructL(RReadStream& aStream);
-	void InternalizeL(RReadStream& aStream);
-	CArrayPtrFlat<CX520AttributeTypeAndValue>* iElements;
-	};
-
-#endif
+/*
+* 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 the class that holds the Distinguished Name of a subject
+*
+*/
+
+
+/**
+ @file 
+ @publishedAll
+ @released
+*/
+#if !defined (__X500DN_H__)
+#define __X500DN_H__
+
+#include <e32base.h>
+#include <e32std.h>
+#include <s32file.h>
+#include <x520ava.h>
+
+class CX500DistinguishedName : public CBase
+/** Holds the Distinguished Name of a subject.
+*
+* A collection of 'attribute type and value' objects, as defined by the X.520 
+* standard.
+*
+* The name used in X.509 certificates is the X.500 Distinguished Name, which 
+* describes a path through an X.500 Directory Information Tree.
+*
+* A Distinguished Name is a series of name-value pairs that uniquely identify 
+* an entity, i.e. the certificate subject. 
+*
+* @publishedAll
+* @released
+*
+* <!-- 
+* This is necessary when working with certificates, certificate requests, directories, etc. 
+* -->
+*/
+	{
+public:
+	/** Creates a new Distinguished Name object from the specified buffer containing 
+	* the encoded binary representation, starting at the specified offset.
+	* 
+	* @param aBinaryData	The encoded binary representation.
+	* @param aPos			The position from which to start decoding.
+	* @return				The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData, TInt& aPos);
+	
+	/** Creates a new Distinguished Name object from the specified buffer containing 
+	* the encoded binary representation, starting at the specified offset, and puts 
+	* a pointer to it onto the cleanup stack.
+	* 
+	* @param aBinaryData	The encoded binary representation.
+	* @param aPos			The position from which to start decoding.
+	* @return				The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData, TInt& aPos);
+	
+	/** Creates a new Distinguished Name 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 Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData);
+	
+	/** Creates a new Distinguished Name object from the specified buffer containing 
+	* the encoded binary representation, and puts a pointer to it 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 Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData);
+	
+	/** Creates a new Distinguished Name object from the specified read stream.
+	* 
+	* Construction is from a stream.
+	* 
+	* @param aStream	Stream from which the contents should be internalised.
+	* @return			The newDistinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewL(RReadStream& aStream);
+	
+	/** Creates a new Distinguished Name object from the specified read stream, and 
+	* puts a pointer to it onto the cleanup stack.
+	* 
+	* @param aStream	Stream from which the contents should be internalised.
+	* @return			The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewLC(RReadStream& aStream);	
+	
+	/** Creates a new Distinguished Name object from the specified array of 'attribute 
+	* type and value' objects.
+	* 
+	* The elements of the specified array are copied into this object.
+	* 
+	* @param aElements	The array of 'attribute type and value' objects to be copied.
+	* @return			The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
+	
+	/** Creates a new Distinguished Name object from the specified array of 'attribute 
+	* type and value' objects, and puts a pointer to it onto the cleanup stack.
+	* 
+	* The elements of the specified array are copied into this object.
+	* 
+	* @param aElements	The array of 'attribute type and value' objects to be copied.
+	* @return			The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewLC(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);	
+	
+	/** Creates a new Distinguished Name object from an existing object.
+	* 
+	* This is equivalent to a copy constructor.
+	* 
+	* @param aName	The Distinguished Name object to be copied.
+	* @return		The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewL(const CX500DistinguishedName& aName);
+	
+	/** Creates a new Distinguished Name object from an existing object, and puts a 
+	* pointer to it onto the cleanup stack.
+	* 
+	* This is equivalent to a copy constructor.
+	* 
+	* @param aName	The Distinguished Name object to be copied.
+	* @return		The new Distinguished Name object. */
+	IMPORT_C static CX500DistinguishedName* NewLC(const CX500DistinguishedName& aName);
+	
+	/** 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. */
+	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
+	
+	/** Gets the number of 'attribute type and value' objects contained by this Distinguished 
+	* Name object.
+	* 
+	* @return	The number of 'attribute type and value' objects. */
+	IMPORT_C TInt Count() const;
+	
+	/** Gets a reference to specific 'attribute type and value' object as identified 
+	* by the specified index.
+	* 
+	* @param aIndex	The index number identifying the specific 'attribute type and 
+	* 				value' object. This number is relative to zero. This value must be non-negative 
+	* 				and less than the number of objects currently contained by this Distinguished 
+	* 				Name object.
+	* @return		The referenced 'attribute type and value' object. */
+	IMPORT_C const CX520AttributeTypeAndValue& Element(TInt aIndex) const;
+	
+	/** Destructor.
+	* 
+	* Frees all resources owned by the object, prior to its destruction. */
+	IMPORT_C ~CX500DistinguishedName(); 
+
+	/** Compares the specified Distinguished Name object with this Distinguished Name 
+	* object.
+	* 
+	* @param aName	The Distinguished Name object to be compared.
+	* @return		ETrue, if the Distinguished Name objects contain exactly the same 'attribute 
+	* 				type and value' objects; EFalse, otherwise.
+	* @see CX520AttributeTypeAndValue::ExactMatchL() 
+	*
+	* <!--	This function checks if all the fields of aName and 
+	*		iElements are the same but not necessarily in the same order. -->
+	*/
+	IMPORT_C TBool ExactMatchL(const CX500DistinguishedName& aName) const;
+
+	/** <!--
+	 // This function checks if the elements of iElements are a superset of
+	 // the fields in aName.
+	 // @param aName We want to check that the fields in aName are present in iElements.
+	 // @return 
+	 // <UL>
+	 // <LI>ETrue if all the fields in aName have a corresponding field in iElements.</LI>
+	 // <LI>EFalse otherwise</LI>
+	 // </UL>
+	 -->
+	* Tests whether all 'attribute type and value' objects contained in the specified 
+	* Distinguished Name object are also contained within this Distinguished Name object.
+	* 
+	* This function checks if the elements of iElements are a superset of the fields in aName.
+	* 
+	* @param aName	The Distinguished Name object to be compared.
+	* @return		ETrue, if all 'attribute type and value' objects contained in the specified 
+	* 				Distinguished Name object are also contained within this Distinguished Name 
+	* 				object; EFalse, otherwise. */
+	IMPORT_C TBool IsWithinSubtreeL(const CX500DistinguishedName& aName) const;
+
+	/** <!--
+	 // This function compares each of the elements in iElements with aElement. The comparison
+	 // is made by the CX520AttributeTypeAndValue::ExactMatchL function.
+	 // @param aElement The element which we want to compare the elements of iElements with.
+	 // @return 
+	 // <UL>
+	 // <LI>ETrue if one of the elements in iElements is equal to aElement.</LI>
+	 // <LI>EFalse otherwise</LI>
+	 // </UL>
+	 -->
+	* Tests whether this Distinguished Name object contains the specified 'attribute 
+	* type and value' object.
+	* 
+	* This function compares each of the elements in iElements with aElement. The comparison
+	* is made by the CX520AttributeTypeAndValue::ExactMatchL() function.
+	* 
+	* @param aElement	The 'attribute type and value' object to be checked.
+	* @return			ETrue, if the specified 'attribute type and value' object is contained 
+	* 					in this Distinguished Name object; EFalse otherwise. */
+	IMPORT_C TBool MatchElementL(const CX520AttributeTypeAndValue& aElement) const;
+	
+	/** Gets the decoded value associated with the specified field/attribute name, 
+	* from the Distinguished Name.
+	* 
+	* @param aFieldName	The field name.
+	* @return			A heap descriptor containing the decoded value associated with the 
+	* 					specified field name. */
+	IMPORT_C HBufC* ExtractFieldL(const TDesC& aFieldName) const;
+	
+	/** Gets the decoded value for the common or organisation name.
+	* 
+	* @return A heap descriptor containing the decoded value of the common or organisation name. */
+	IMPORT_C HBufC* DisplayNameL() const;
+
+	/** Encodes a DN into an ASN.1 object tree.
+	* 
+	* Note that the tree has the following format:
+	* @code
+    *         SEQUENCE-OF
+    *             SET-OF
+    *                 SEQUENCE-OF
+    *                     OID
+    *                     value (usually OCTET STRING)
+    *             ...
+    * @endcode
+	* 
+	* A SEQUENCE-OF object with a changed tag is used instead of 
+	* a SET-OF object. This should be all right as long as it 
+	* contains only one child, because otherwise child order in 
+	* a SET-OF becomes important.
+	* 
+	* This function does not introduce an additional dependency 
+	* on ASN1 library because X500 library already depends on 
+	* it -- the attribute type/value class stores and manipulated 
+	* ASN.1 encodings as its values.
+	* 	
+	* @return	ASN.1 sequence object containing the DN, 
+	* 			pushed on the cleanup stack.
+	*/
+	IMPORT_C CASN1EncSequence* EncodeASN1LC() const;
+
+	/** Encodes a DN into an ASN.1 object tree. 
+	* 
+	* See note in the description of #EncodeASN1LC for the explanation of 
+	* the resulting encoding tree format.
+	* 	
+	* @return	ASN.1 sequence object containing the DN. */
+	IMPORT_C CASN1EncSequence* EncodeASN1L() const;
+
+private:
+	CX500DistinguishedName();
+	void ConstructL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
+	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
+	void ConstructL(RReadStream& aStream);
+	void InternalizeL(RReadStream& aStream);
+	CArrayPtrFlat<CX520AttributeTypeAndValue>* iElements;
+	};
+
+#endif