/*
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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:   Contains NcdNodeIdentifierEditor namespace
*
*/


#ifndef NCD_NODE_IDENTIFIER_EDITOR_H
#define NCD_NODE_IDENTIFIER_EDITOR_H


#include <e32std.h>

class CNcdNodeIdentifier;


/**
 *  This class object should be used to create node and metadata
 *  identifiers instead of directly creating them in different places
 *  of code.
 */
namespace NcdNodeIdentifierEditor
    {
    
    // Functions to create correct node identifiers

    /**
     * @param aParentIdentifier
     * @param aMetaDataIdentifier
     * @return CNcdNodeIdentifier* The identifier that has been created by using the
     * parent id and the metadata id. Ownership is transferred.
     */
    CNcdNodeIdentifier* CreateNodeIdentifierLC( const CNcdNodeIdentifier& aParentIdentifier,
                                                const CNcdNodeIdentifier& aMetaDataIdentifier );

    void MarkMetaDataPartL( TLex& aMetaId );
    
    /**
     * Gets parent id and namespace from child's id.
     * If there is no parent the values will be set to KNullDesC.
     *
     * @param aChildId Child's id.
     * @param aParentId Will contain parent's id upon return.
     * @param aParentId Will contain parent's namespace upon return.
     */
    void GetParentIdAndNsL( const TDesC& aChildId, TPtrC& aParentId, TPtrC& aParentNs );
    
    /**
     * @see CNcdNodeIdentifierEditor::CreateMetaIdentifierLC
     */
    CNcdNodeIdentifier* CreateMetaDataIdentifierL( const CNcdNodeIdentifier& aNodeIdentifier );

    /**
     * @param aNodeIdentifier The identifier that identifies the node. (Contains parent info in id).
     * @return CNcdNodeIdentifier* Identifier of the metadata of the given node.
     */
    CNcdNodeIdentifier* CreateMetaDataIdentifierLC( const CNcdNodeIdentifier& aNodeIdentifier );
    
    /**
     * 
     */
    TBool DoesMetaDataIdentifierMatchL( const CNcdNodeIdentifier& aNodeIdentifier,
        const TDesC& aMetaId, const TDesC& aMetaNameSpace, const TUid& aMetaUid );

    TBool DoesMetaDataIdentifierMatchL( const CNcdNodeIdentifier& aMetaDataIdentifier,
        const CNcdNodeIdentifier& aNodeIdentifier );

    /**
     * All the root identifiers have the same namespace but the client id
     * is used also as the id.
     *
     * @param aUid Uid of the client whose root identifier is asked.
     * @return CNcdNodeIdentifier* Identifier of the root node of a given client.
     */
    CNcdNodeIdentifier* CreateRootIdentifierForClientLC( const TUid& aUid );

    /**
     * All the search root identifiers have the same namespace but the client id
     * is used also as the id.
     *
     * @param aUid Uid of the client whose search root identifier is asked.
     * @return CNcdNodeIdentifier* Identifier of the search root node of a given client.
     */
    CNcdNodeIdentifier* CreateSearchRootIdentifierForClientLC( const TUid& aUid );

    /**
     * This function creates the identifier for the temporary node. Temporary nodes are not child
     * of any other node. So, they will be left hanging themselves.
     *
     * @param aMetaDataIdentifier Identifies the metadata that this temporary node will contain.
     * @return CNcdNodeIdentifier* Identifies the temporary node.
     */ 
    CNcdNodeIdentifier* CreateTemporaryNodeIdentifierLC( const CNcdNodeIdentifier& aMetaDataIdentifier );    


    // Functions that can provide information that is included to the identifiers

    /**
     * This function returns the depth of the node in the node hierarchy.
     * 
     * @note Namespaces are omitted in the node id. So, only the metadata id parts are
     * counted for the depth. Depth is zero if only one metadata id is included to the node id.
     *
     * @param aNodeIdentifier Identifier of the node. The node id contains also
     * parent names. So, the depth can be calculated from id descriptor.
     * @return TInt The depth of the node. The root level is zero.
     */
    TInt NodeDepthL( const CNcdNodeIdentifier& aNodeIdentifier );

    /**
     * This function checks if the given identifier identifies
     * some root. The namespace information of the identifier
     * is used to check this. So, this function can be used
     * for both metadata and nodes. There may be multiple 
     * namespaces that identify different roots. For example, 
     * normal node root or search root etc.
     * 
     * @param aIdentifier Identifier that is used to check
     * if it identifies root some root. 
     * @return TBool ETrue if identifier identifies root. Else
     * EFalse.
     */
    TBool IdentifiesSomeRoot( const CNcdNodeIdentifier& aIdentifier );

    /**
     * This function check if the given identifier identifies
     * some temporary node, which does not belong under some root
     * node. In other words, the node just hangs by itself.
     *
     * @param aIdentifier The identifier of the node that is checked.
     * @return TBool ETrue if the node is temporary node. Else EFalse.
     */
    TBool IdentifiesTemporaryNodeL( const CNcdNodeIdentifier& aIdentifier );

    /**
     * @param aParentNodeIdentifier A supposed parent
     * @param aChildNodeIdentifier A supposed child or grand child etc. of parent
     * @return TBool ETrue if the child is the child or grand child etc. of the 
     * given parent. Else EFalse.
     */
    TBool ParentOf( const CNcdNodeIdentifier& aParentNodeIdentifier,
                    const CNcdNodeIdentifier& aChildNodeIdentifier );    


    /**
     * This function parses the child identifier and creates the parent information
     * from the child identifier.
     * @param aChildNodeIdentifier A supposed child or grand child etc. of parent
     * @return CNodeIdentifier* The identifier of the parent of the node that is identified
     * by the aChildNodeIdentifier.
     * @exception Leaves with KErrArgument if aChildNodeIdentifier contains empty fields
     * or if no parent can be deducted from the id (e.g. root node's identifier).
     */    
    CNcdNodeIdentifier* ParentOfLC( const CNcdNodeIdentifier& aChildNodeIdentifier );    

    /**
     * This function checks if the given identifier identifies
     * some search node.
     *
     * @param aIdentifier The identifier of the node that is checked.
     * @return TBool ETrue if the node is a search node. Else EFalse.
     */
    TBool IdentifiesSearchNodeL( const CNcdNodeIdentifier& aIdentifier );

    }

#endif // NCD_NODE_IDENTIFIER_EDITOR_H