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