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