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 MNcdNodeContainer interface

    15 *

    16 */

    17 

    18 

    19 #ifndef M_NCD_NODE_CONTAINER_H

    20 #define M_NCD_NODE_CONTAINER_H

    21 

    22 

    23 #include <e32cmn.h>

    24 

    25 #include "catalogsbase.h"

    26 #include "ncdinterfaceids.h"

    27 #include "ncdchildloadmode.h"

    28 #include "ncdcontainertype.h"

    29 

    30 

    31 class MNcdNode;

    32 class MNcdLoadNodeOperation;

    33 class MNcdLoadNodeOperationObserver;

    34 

    35 /**

    36  *  Container may contain other nodes.

    37  *  This interface provides functions that can be used to

    38  *  get the nodes of the container. Also, a convenience function

    39  *  to load the content for the child nodes is provided.

    40  *

    41  *  This interface can be queried from node objects that are containers,

    42  *  after the node has been initialized.

    43  *

    44  *  

    45  */

    46 class MNcdNodeContainer : public virtual MCatalogsBase

    47     {

    48 

    49 public:

    50 

    51     /**

    52      * Unique identifier for the interface, required for all MCatalogsBase interfaces.

    53      *

    54      * 

    55      */

    56     enum { KInterfaceUid = ENcdNodeContainerUid };

    57     

    58     /**

    59      * Returns the child node count for this container. The count may be

    60      * used to get the upper limit for indexing the contained child nodes

    61      * with the ChildL() method.

    62      *

    63      * @return The number of the children in this container.

    64      */

    65     virtual TInt ChildCount() const = 0;

    66 

    67 

    68     /**

    69      * Returns a child (contained node) of this container.

    70      *

    71      * @note The reference count of the node is increased by one. So,

    72      * Release function of the node should be called when the node

    73      * is not needed anymore.

    74      *

    75      * @param aIndex is the index to the child of this container.

    76      * @return Pointer to the child node, may be an item or another container.

    77      *  Counted, Release() must be called after use.

    78      * @exception Leave System wide error code.

    79      * @exception Panic ENcdPanicIndexOutOfRange Index out of range.

    80      */

    81     virtual MNcdNode* ChildL( TInt aIndex ) = 0;

    82 

    83 

    84     /**

    85      * Loads node information from the content provider for the

    86      * children of this container.

    87      *

    88      * The loading of children is started from the given index.

    89      * Size informs the maximum number of children that are loaded.

    90      *

    91      * @param aIndex The index of the child that will be the first one

    92      *  to be loaded.

    93      * @param aSize The maximum number of children to load.

    94      *  For special cases: if KMaxTInt is given, then it will be

    95      *  interpreted so that all the children after aIndex should be loaded. 

    96      *  By using KMaxTInt, a parent container refresh may be skipped and 

    97      *  all the children may be requested from server even if parent's 

    98      *  child count information may not be valid. In normal cases, usage of 

    99      *  KMaxTInt should be avoided. Instead, refresh the parent first and 

   100      *  use the correct child count value. KMaxTInt may not be supported 

   101      *  for all type of containers. If not supported, then a leave will occur.  

   102      * @param aMode Load mode, determines whether structure, metadata or both

   103      *  will be loaded.

   104      * @param aObserver Observer for the operation.

   105      * @return Pointer to an operation that can 

   106      *  be used to check the progressing of the loading. Counted,

   107      *  Release() must be called after use.

   108      * @exception Leave System wide error code.

   109      *  KErrNotFound if trying to load metadata and no structure is present.

   110      *  KNcdErrorParallelOperationNotAllowed if a parallel client is running

   111      *  an operation for the same metadata, see MNcdOperation for full explanation.

   112      */

   113     virtual MNcdLoadNodeOperation* LoadChildrenL( 

   114         TInt aIndex, TInt aSize, TNcdChildLoadMode aMode,

   115         MNcdLoadNodeOperationObserver& aObserver ) = 0;

   116         

   117     /**

   118      * Tells the type of the folder. It may be a normal folder or a catalog.

   119      *

   120      * @return The type.

   121      */

   122     virtual TNcdContainerType ContainerType() const = 0;

   123 

   124 

   125 protected:

   126 

   127     /**

   128     * Destructor.

   129     *

   130     * @see MCatalogsBase::~MCatalogsBase

   131     */

   132     virtual ~MNcdNodeContainer() {}

   133 

   134     };

   135 

   136 

   137 #endif // M_NCD_NODE_CONTAINER_H