1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Contains CNcdNode class

    15 *

    16 */

    17 

    18 

    19 #ifndef NCD_NODE_H

    20 #define NCD_NODE_H

    21 

    22 

    23 #include <e32cmn.h>

    24 #include <s32mem.h>

    25 

    26 #include "catalogscommunicable.h"

    27 #include "ncdstoragedataitem.h"

    28 #include "ncdnodemanager.h"

    29 #include "ncdnodeclassids.h"

    30 #include "ncdnodeidentifier.h"

    31 // This is included for the state enum value

    32 #include "ncdnode.h"

    33 

    34 class CNcdNodeLink;

    35 class CNcdNodeMetaData;

    36 class CNcdNodeIdentifier;

    37 class CNcdNodeUserData;

    38 class CNcdNodeSeen;

    39 

    40 

    41 /**

    42  *  This class object provides node specific functions.

    43  *  Node contains additional classes that will contain more node

    44  *  or metadata specific information.

    45  *

    46  *  @lib ?library

    47  *  @since S60 ?S60_version *** for example, S60 v3.0

    48  */

    49 class CNcdNode : public CCatalogsCommunicable,

    50                  public MNcdStorageDataItem

    51     {

    52 public:

    53 

    54     static TInt Compare( const CNcdNode& aFirst, const CNcdNode& aSecond )

    55         {

    56         return CNcdNodeIdentifier::Compare( 

    57             aFirst.Identifier(), 

    58             aSecond.Identifier() );

    59         }

    60         

    61 public:

    62 

    63     /**

    64      * Destructor

    65      */

    66     virtual ~CNcdNode();

    67     

    68 

    69     /**

    70      * @return CNcdNodeIdentifier& Unique identifier of this node.

    71      */

    72     virtual const CNcdNodeIdentifier& Identifier() const;

    73     

    74     /**

    75      * Retrieves the data type that informs what class the data is for.

    76      * By checking the data type information, an InternalizeL function

    77      * of a right class can be called when the object data is set

    78      * from the storage.

    79      * The data type may be decided and set in a factory that creates object.

    80      * The factory should know which integer is reserved for which class.

    81      *

    82      * @return TInt The integer that describes the data type. 

    83      */

    84     NcdNodeClassIds::TNcdNodeClassId ClassId() const;

    85 

    86 

    87     /**

    88      * @return The nodemanager that has created this node.

    89      */

    90     CNcdNodeManager& NodeManager() const;

    91 

    92 

    93     /**

    94      * Uses CreateLinkL to create the link if the link does not already

    95      * exist. If a new link is created it is set as a link for the node.

    96      *

    97      * @return CNcdNodeLink& The link that has been set for this node.

    98      */

    99     CNcdNodeLink& CreateAndSetLinkL();

   100 

   101     /**

   102      * @return CNcdNodeLink& Reference to the node link. 

   103      * @exception KErrNotFound if node link has not been set.

   104      */

   105     CNcdNodeLink& NodeLinkL() const;

   106 

   107     /**

   108      * @return CNcdNodeLink Pointer to the node link. NULL if no link

   109      * is set. Ownership is NOT transferred. 

   110      */

   111     CNcdNodeLink* NodeLink() const;

   112     

   113     /** 

   114      * @return The node seen object of the node.

   115      */

   116     CNcdNodeSeen& NodeSeen() const; 

   117    

   118  

   119     /**

   120      * Internalizes data to the node link. If the node link does

   121      * not exists it is created by callin CreateLinkL which should be

   122      * overloaded in child classes to give the right kind of link.

   123      *

   124      * @param

   125      * @param

   126      */

   127     virtual void InternalizeLinkL( const MNcdPreminetProtocolEntityRef& aData,

   128                                    const CNcdNodeIdentifier& aParentIdentifier,

   129                                    const CNcdNodeIdentifier& aRequestParentIdentifier,

   130                                    const TUid& aClientUid );

   131     

   132     

   133     /**

   134      * @note Node manager is used to set the metadata

   135      * that corresponds to the node link.

   136      *

   137      * @return CNcdNodeMetaData& Reference to the metadata.

   138      * @exception KErrNotFound if meta data or node link has not been set.

   139      */

   140     CNcdNodeMetaData& NodeMetaDataL() const;

   141     

   142     /**

   143      * @return CNcdNodeMetaData* Pointer to the metadata, NULL if no metadata

   144      * is set. Ownership is NOT transferred.

   145      */

   146     CNcdNodeMetaData* NodeMetaData() const;

   147 

   148     /**

   149      * Sets the metadata. Does not delete old one because metadata is owned

   150      * byt the nodemanager.

   151      *

   152      * @param aMetaData is the new meta data that this node will contain.

   153      * @exception KErrBadName if the metadata is not of the accepted type.

   154      */

   155     void SetNodeMetaDataL( CNcdNodeMetaData& aMetaData );

   156     

   157     /**

   158      * Gives information about the state of the node. This information can be used to

   159      * check whether the item data has been loaded or if the data is expired.

   160      *

   161      * @return The state of the node.

   162      */

   163     MNcdNode::TState State() const;

   164         

   165 

   166 public: // CCatalogsCommunicable

   167 

   168     /**

   169      * @see CCatalogsCommunicable::ReceiveMessage

   170      */

   171     virtual void ReceiveMessage( MCatalogsBaseMessage* aMessage,

   172                                  TInt aFunctionNumber );

   173 

   174     /**

   175      * @see CCatalogsCommunicable::CounterPartLost

   176      */

   177     virtual void CounterPartLost( const MCatalogsSession& aSession );

   178 

   179 

   180 public: // MNcdStorageDataItem

   181 

   182     /**

   183      * @see MNcdStorageDataItem::ExternalizeL

   184      */

   185     virtual void ExternalizeL( RWriteStream& aStream );

   186 

   187 

   188     /**

   189      * @see MNcdStorageDataItem::InternalizeL

   190      */

   191     virtual void InternalizeL( RReadStream& aStream );

   192 

   193 

   194 protected:

   195 

   196     /**

   197      * Constructor

   198      */

   199     CNcdNode( CNcdNodeManager& aNodeManager,

   200               NcdNodeClassIds::TNcdNodeClassId aNodeClassId,

   201               NcdNodeClassIds::TNcdNodeClassId aAcceptedLinkClassId,

   202               NcdNodeClassIds::TNcdNodeClassId aAcceptedMetaDataClassId );

   203     

   204     /**

   205      * @param atIdentifier Identifier of this node. The identifier is unique

   206      * to all the nodes.

   207      */

   208     virtual void ConstructL( const CNcdNodeIdentifier& aIdentifier );

   209         

   210 

   211     /**

   212      * Child classes should implement this function. 

   213      * So, the right type of link will be created when this creator is called.

   214      * This function will create the link only once. If the link has already 

   215      * been created then the old link will be returned.

   216      *

   217      * @param CNcdNodeLink* The created link or the old link if it already existed.

   218      */

   219     virtual CNcdNodeLink* CreateLinkL() = 0;

   220 

   221 

   222     // Here are all the functions that are used when ReceiveMessageL is called and

   223     // the functionality is delegated according to the given function number.

   224     

   225     /**

   226      *

   227      */

   228     void InternalizeRequestL( MCatalogsBaseMessage& aMessage ) const;

   229 

   230     /**

   231      * Child classes should overload this or add their own data after

   232      * the parent class data.

   233      */    

   234     virtual void ExternalizeDataForRequestL( RWriteStream& aStream ) const;    

   235 

   236 

   237     void LinkHandleRequestL( MCatalogsBaseMessage& aMessage ) const;

   238     void MetadataHandleRequestL( MCatalogsBaseMessage& aMessage ) const;

   239     void NodeSeenHandleRequestL( MCatalogsBaseMessage& aMessage ) const;

   240     void ClassIdRequestL( MCatalogsBaseMessage& aMessage ) const;

   241     void ReleaseRequest( MCatalogsBaseMessage& aMessage ) const;

   242     

   243     

   244 private:

   245     

   246     // Prevent if not implemented

   247     CNcdNode( const CNcdNode& aObject );

   248     CNcdNode& operator =( const CNcdNode& aObject );

   249 

   250 

   251     // This is used to forward the internalization/externalization

   252     // to the link

   253     void ExternalizeLinkL(  RWriteStream& aStream ); 

   254     void InternalizeLinkL( RReadStream& aStream );

   255 

   256     void DoReceiveMessageL( 

   257         MCatalogsBaseMessage& aMessage, 

   258         TInt aFunctionNumber );

   259 

   260 

   261 private: // data

   262 

   263     // Manager manages and owns nodes.

   264     // This class does not own the manager.    

   265     CNcdNodeManager& iNodeManager;

   266 

   267     NcdNodeClassIds::TNcdNodeClassId iNodeClassId;

   268 

   269     // The link type is used to check if the given link is of

   270     // the right type. 

   271     NcdNodeClassIds::TNcdNodeClassId iAcceptedLinkClassId;

   272     

   273     // The metadata type is used to check if the given metadata is of

   274     // the right type. 

   275     NcdNodeClassIds::TNcdNodeClassId iAcceptedMetaDataClassId;

   276 

   277     // This is the identifier of the node. Owns.

   278     CNcdNodeIdentifier* iNodeIdentifier;

   279     

   280 protected:

   281     // The message is set when ReceiveMessage is called. The message

   282     // is used in the CounterPartLost-function that informs the message

   283     // if the session has been lost.

   284     MCatalogsBaseMessage* iMessage;

   285     

   286 private:

   287     // These objects provide additional functionality for the node.

   288 

   289     // This class owns node link if it has been set.

   290     CNcdNodeLink* iNodeLink;

   291 

   292     // This class does not own meta data.

   293     CNcdNodeMetaData* iNodeMetaData;

   294     

   295     // This class owns the seen information.

   296     CNcdNodeSeen* iNodeSeen;

   297     };

   298 

   299 

   300 #endif // NCD_NODE_H