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

    15 *

    16 */

    17 

    18 

    19 #ifndef NCD_NODE_FOLDER_H

    20 #define NCD_NODE_FOLDER_H

    21 

    22 

    23 #include <e32cmn.h>

    24 

    25 #include "ncdnodeimpl.h"

    26 

    27 class CNcdNodeIdentifier;

    28 class CNcdChildEntity;

    29 class CNcdNodeFolderLink;

    30 class CNcdNodeSeenFolder;

    31 

    32 

    33 /**

    34  *  ?one_line_short_description

    35  *

    36  *  ?more_complete_description

    37  *

    38  *  @lib ?library

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

    40  */

    41 class CNcdNodeFolder : public CNcdNode

    42     {

    43     

    44 public:

    45 

    46     /**

    47      * NewL

    48      *

    49      * @return CNcdNodeFolder* Pointer to the created object 

    50      * of this class.

    51      */

    52     static CNcdNodeFolder* NewL( CNcdNodeManager& aNodeManager,

    53                                  const CNcdNodeIdentifier& aIdentifier );

    54     

    55     /**

    56      * NewLC

    57      *

    58      * @return CNcdNodeFolder* Pointer to the created object 

    59      * of this class.

    60      */

    61     static CNcdNodeFolder* NewLC( CNcdNodeManager& aNodeManager,

    62                                   const CNcdNodeIdentifier& aIdentifier );

    63 

    64 

    65     /**

    66      * Destructor

    67      */

    68     virtual ~CNcdNodeFolder();

    69 

    70 

    71     /** 

    72      * Getter for child count.

    73      * 

    74      * @note This is the count of children in the child array, not the expected

    75      * child count that comes from server!

    76      */

    77     virtual TInt ChildCount() const;

    78 

    79     /**

    80      * Returns the child node by the given index.

    81      *

    82      * @note Returns the available children, can be indexed against ChildCount

    83      */

    84     virtual const CNcdNodeIdentifier& ChildL( TInt aIndex ) const;

    85     

    86     /**

    87      * Returns the whole child array.

    88      */

    89     const RPointerArray<CNcdChildEntity>& ChildArray() const;

    90     

    91     /** 

    92      * Getter for server child count.

    93      * 

    94      * Uses CNcdNodeFolderLink::ExpectedChildrenCount

    95      *

    96      * @exception KErrNotFound if link not set.

    97      */

    98     virtual TInt ServerChildCountL() const;

    99     

   100     /** 

   101      * Getter for child identifier by server child index.

   102      *

   103      * Indexed against ServerChildCountL. Some children may be unavailable

   104      * because of paging, so this function should be used with care.

   105      *

   106      * @param aIndex The index of the child (i.e. index on server).

   107      * @return Child identifier for the given index.

   108      * @exception KErrNotFound if the child entity is not found.

   109      */

   110     virtual const CNcdNodeIdentifier& ChildByServerIndexL( TInt aIndex ) const;

   111     

   112     /** 

   113      * Getter for child entity by server child index.

   114      *

   115      * Indexed against ServerChildCountL. Some children may be unavailable

   116      * because of paging, so this function should be used with care.

   117      *

   118      * @param aIndex The index of the child (i.e. index on server).

   119      * @return Child entity for the given index.

   120      * @exception KErrNotFound if the child entity is not found.

   121      */

   122     virtual const CNcdChildEntity& ChildEntityByServerIndexL( TInt aIndex ) const;

   123     

   124     

   125     

   126     /**

   127      * Adds a child to this folder if not present already.

   128      *

   129      * @param aNodeIdentifier Identifier of the node.

   130      * @param aIndex Index of the child node (i.e. index of the actual node on server)

   131      * @param aTransparent Defines whether this child is transparent.

   132      * @param aNodeType Type of the child node (folder, item etc.).

   133      * @return ETrue if the child was added. Else EFalse (children

   134      * are inserted only once).

   135      */

   136     virtual TBool ReplaceChildL( 

   137         const CNcdNodeIdentifier& aNodeIdentifier,

   138         TInt aIndex,

   139         TBool aTransparent,

   140         CNcdNodeFactory::TNcdNodeType aNodeType );

   141     

   142     virtual TBool InsertChildL( 

   143         const CNcdNodeIdentifier& aNodeIdentifier,

   144         TInt aIndex,

   145         TBool aTransparent,

   146         CNcdNodeFactory::TNcdNodeType aNodeType );

   147         

   148     virtual TBool AppendChildL( 

   149         const CNcdNodeIdentifier& aNodeIdentifier,

   150         TBool aTransparent,

   151         CNcdNodeFactory::TNcdNodeType aNodeType );

   152         

   153     CNcdNodeFolderLink& FolderLinkL() const;

   154 

   155     CNcdNodeSeenFolder& NodeSeenFolder() const;

   156 

   157     void RemoveChild( const CNcdNodeIdentifier& aNodeIdentifier );

   158     

   159     /**

   160      * Removes children from the child list and database

   161      */

   162     void RemoveChildrenL();

   163     

   164     /**

   165      * Removes children only from the child list

   166      */

   167     void RemoveChildren();

   168     

   169     /**

   170      * Stores current children to previous child list and sets the

   171      * previous child count.

   172      */

   173     void StoreChildrenToPreviousListL();

   174     

   175     /**

   176      * Stores the given child list as previous child list and sets the

   177      * previous child count.

   178      *

   179      * @param aPreviousChildren The previous children.

   180      * @param aPreviousChildCount.

   181      */

   182     void StoreChildrenToPreviousListL(

   183         const RPointerArray<CNcdChildEntity>& aPreviousChildren,

   184         TInt aPreviousChildCount );

   185     

   186     /**

   187      * Checks that have this folder's children been loaded previously.

   188      * This is needed to differentiate first time loading of the folder from

   189      * consequent loads.

   190      *

   191      * @note Does not indicate that the children are in cache or

   192      * anything else other than what is described above.

   193      *

   194      * @return ETrue if children have been loaded previously, EFalse otherwise.

   195      */

   196     TBool ChildrenPreviouslyLoaded();

   197     

   198     /**

   199      * Setter for the children previously loaded flag.

   200      *

   201      * @param aChildrenPreviouslyLoaded Default value is ETrue.

   202      * @note This flag should be unset only in special occaisions

   203      * such as unsetting for root node on cache clear.

   204      */

   205     void SetChildrenPreviouslyLoaded( TBool aChildrenPreviouslyLoaded = ETrue );

   206     

   207     /**

   208      * Getter for previous child count.

   209      *

   210      * @note Not persistently stored to db.

   211      * @return The previous child count or KErrNotFound if not set.

   212      */

   213     TInt PreviousChildCount();

   214     

   215     /**

   216      * Getter for previous child array.

   217      *

   218      * @note The array is not persistently stored to db.

   219      * @return An array containing previous children.

   220      */

   221     const RPointerArray<CNcdChildEntity>& PreviousChildArray();

   222     

   223     

   224     /**

   225      * Sets folder's children as expired and removes them from the child array

   226      * and deletes their metadatas from disk cache

   227      */

   228     void ExpireAndRemoveChildrenL();

   229     

   230 

   231 public: // CNcdNode

   232 

   233     /**

   234      * @see CNcdNode::ReceiveMessage

   235      */

   236     virtual void ReceiveMessage( MCatalogsBaseMessage* aMessage,

   237                                  TInt aFunctionNumber );

   238 

   239 

   240     /**

   241      * @see CNcdNode::ExternalizeL

   242      */

   243     virtual void ExternalizeL( RWriteStream& aStream );

   244 

   245 

   246     /**

   247      * @see CNcdNode::InternalizeL

   248      */

   249     virtual void InternalizeL( RReadStream& aStream );

   250 

   251 

   252 

   253 protected:

   254 

   255     /**

   256      * @see CNcdNode::CNcdNode

   257      */

   258     CNcdNodeFolder( CNcdNodeManager& aNodeManager,

   259         NcdNodeClassIds::TNcdNodeClassId aNodeClassId = NcdNodeClassIds::ENcdFolderNodeClassId, 

   260         NcdNodeClassIds::TNcdNodeClassId aAcceptedLinkClassId = NcdNodeClassIds::ENcdFolderNodeLinkClassId,

   261         NcdNodeClassIds::TNcdNodeClassId aAcceptedMetaDataClassId = NcdNodeClassIds::ENcdFolderNodeMetaDataClassId );

   262     

   263     /**

   264      * @see CNcdNode::ConstructL

   265      */

   266     virtual void ConstructL( const CNcdNodeIdentifier& aIdentifier );

   267 

   268 

   269     /**

   270      * @see CNcdNode::CreateLinkL

   271      */

   272     virtual CNcdNodeLink* CreateLinkL();

   273 

   274 

   275     /** 

   276      * @see CNcdNode::ExternalizeDataForRequestL

   277      */

   278     virtual void ExternalizeDataForRequestL( RWriteStream& aStream ) const;    

   279 

   280 

   281     /**

   282      * @param aStream that will contain the child array data.

   283      */

   284     void ExternalizeChildArrayL( RWriteStream& aStream ) const;

   285 

   286     /**

   287      * This function is required because the proxy may require different

   288      * child identifiers into its array. The child classes of this class

   289      * may provide its own implementation to create child arrays for proxy.

   290      * This implementation uses ExternalizeChildArrayL.

   291      *

   292      * @param aStream that will contain the child array data.

   293      */

   294     virtual void ExternalizeChildArrayForRequestL( RWriteStream& aStream ) const;

   295     

   296     void NodeSeenFolderHandleRequestL( MCatalogsBaseMessage& aMessage ) const;  

   297     

   298     

   299 private:

   300     

   301     // Prevent these two if they are not implemented

   302     CNcdNodeFolder( const CNcdNodeFolder& aObject );

   303     CNcdNodeFolder& operator =( const CNcdNodeFolder& aObject );

   304 

   305 

   306 private: // data

   307 

   308     // This array contains the identifying info of child nodes.

   309     // The information can be used to get the actual node from

   310     // the node manager. The identityinfo is used here instead of

   311     // actual references to the nodes because the manager will

   312     // handle the destruction of the nodes. Now, there is not

   313     // danger for NULL pointer errors.

   314     RPointerArray<CNcdChildEntity> iChildren;

   315     

   316     // Determines whether the previous child list has been populated.

   317     // NOTE: This is not stored to db currently.

   318     //TBool iPreviousChildrenStored;

   319     

   320     // Previous child list is stored here when refreshing folder.

   321     // Nodes not found from this list are considered new.

   322     // NOTE: This array is not stored to db currently.

   323     RPointerArray<CNcdChildEntity> iPreviousChildren;

   324     

   325     // Previous child count (i.e. the server child count)

   326     // KErrNotFound if not set;

   327     // NOTE: This is not stored to db currently. 

   328     TInt iPreviousChildCount;

   329     

   330     // Defines whether children of this folder have been loaded previously.

   331     // This is needed to differentiate first time loading of the folder from

   332     // consequent loads. This flag is persistently stored to db.

   333     // NOTE: This flag does not indicate that the children are in cache or

   334     // anything else other than what is described above.

   335     TBool iChildrenPreviouslyLoaded;

   336     

   337     // Implements the seen interface of folders.

   338     CNcdNodeSeenFolder* iNodeSeenFolder;

   339     

   340     };

   341 

   342 

   343 #endif // NCD_NODE_FOLDER_H