--- 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