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

    15 *

    16 */

    17 

    18 

    19 #ifndef M_NCD_NODE_H

    20 #define M_NCD_NODE_H

    21 

    22 

    23 #include <e32cmn.h>

    24 #include <e32std.h>

    25 

    26 #include "catalogsbase.h"

    27 #include "catalogsarray.h"

    28 #include "ncdinterfaceids.h"

    29 

    30 

    31 class MNcdNodeContainer;

    32 class MNcdLoadNodeOperation;

    33 class MNcdLoadNodeOperationObserver;

    34 class MNcdOperation;

    35 

    36 

    37 /**

    38  *  Node contains the basic information about the content.

    39  *  The interface also provides a load function that must be used to

    40  *  initialize the node, before accessing other information.

    41  *

    42  *  When the UI gets the node, the node may not contain any information

    43  *  except from the node state. The state may be checked by calling

    44  *  MNcdNode::State(). MNcdNode::LoadL() can then be called to load

    45  *  the content for the node, if the state is uninitialized or expired.

    46  *

    47  *  @note The actual content information, such as name, description etc. are

    48  *  available through the MNcdNodeMetadata interface that can be queried from

    49  *  node objects. There are various other additional node interfaces as well

    50  *  that all offer different functionality and information about the node. The

    51  *  interfaces are not available at all times, they have different criteria for

    52  *  becoming available. For example, the MNcdNodeMetadata interface becomes

    53  *  available for a node when its metadata is loaded, so if it is not available

    54  *  at first, it can be made available by calling the node's MNcdNode::LoadL()

    55  *  method.

    56  *

    57  *  

    58  *  @see MNcdNodeMetadata

    59  *  @see MNcdNodeContainer

    60  *  @see MNcdNodeContent

    61  *  @see MNcdNodeDependency

    62  *  @see MNcdNodeDownload

    63  *  @see MNcdNodeIcon

    64  *  @see MNcdNodeInstall

    65  *  @see MNcdNodePreview

    66  *  @see MNcdNodePurchase

    67  *  @see MNcdNodeScreenshot

    68  *  @see MNcdNodeSearch

    69  *  @see MNcdNodeSkin

    70  *  @see MNcdNodeSubscribe

    71  *  @see MNcdNodeUpgrade

    72  *  @see MNcdNodeUriContent

    73  *  @see MNcdNodeUserData

    74  */

    75 class MNcdNode : public virtual MCatalogsBase

    76     {

    77 

    78 public:

    79 

    80     /**

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

    82      *

    83      * 

    84      */

    85     enum { KInterfaceUid = ENcdNodeUid };

    86 

    87 

    88     /**

    89      * TNcdNode::TState gives information in what state the node is at the moment.

    90      * This information can be used to check if the node information should be

    91      * loaded over network or from local cache.

    92      *

    93      * 

    94      */

    95     enum TState

    96         {

    97         /**

    98          * Node is not initialized and the data should

    99          * be loaded from either local cache, or over network.

   100          */

   101         EStateNotInitialized,

   102 

   103         /** Node data is up to date. */

   104         EStateInitialized,

   105 

   106         /** Node data is expired and should be reloaded over network. */

   107         EStateExpired

   108         };

   109 

   110 

   111     /**

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

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

   114      * 

   115      * 

   116      * @return The state of the node.

   117      */

   118     virtual TState State() const = 0;

   119 

   120 

   121     /**

   122      * Gets the node id.

   123      *

   124      * 

   125      * @return Id of the node.

   126      */

   127     virtual const TDesC& Id() const = 0;

   128 

   129 

   130     /**

   131      * All nodes and their content are part of a namespace. Within the

   132      * namespace, node identifiers are unique. This function returns the namespace

   133      * of this node and its contents.

   134      *

   135      * 

   136      * @return The namespace identifier. If the protocol has not defined

   137      *         any value, an empty descriptor is returned.

   138      */

   139     virtual const TDesC& Namespace() const = 0;

   140 

   141 

   142     /**

   143      * Gets the name of the catalog source for the node.

   144      *

   145      * 

   146      * @return Name of the catalog source where the node is loaded from. An

   147      *  empty string is returned if the source name is not defined.

   148      */

   149     virtual const TDesC& CatalogSourceName() const = 0;

   150 

   151 

   152     /**

   153      * Retrieves the reference to the parent of this node.

   154      *

   155      * 

   156      * @return The parent of this node. NULL if the node

   157      *  has no parent. Counted, Release() must be called

   158      *  after use.

   159      * @exception Leave System wide error code, 

   160      *  KErrNotFound if the parent node is not loaded.

   161      */

   162     virtual MNcdNodeContainer* ParentL() const = 0;

   163     

   164 

   165     /**

   166      * Loads node information from the content provider.

   167      *

   168      * @note Should be called when a folder node needs to be refreshed, clears all

   169      *  child nodes for folders!

   170      *

   171      * 

   172      * @param aObserver Observer for the operation.

   173      * @return Pointer to an operation object that can be

   174      *  used to check the loading progress. Counted, Release() must be called

   175      *  after use.     

   176      * @exception Leave System wide error code.

   177      *  KNcdErrorParallelOperationNotAllowed if a parallel client is running

   178      *  an operation for the same metadata. See MNcdOperation for full explanation.

   179      */

   180     virtual MNcdLoadNodeOperation* LoadL( MNcdLoadNodeOperationObserver& aObserver ) = 0;

   181 

   182 

   183     /**

   184      * Returns a list of currently active operations of this node for progress

   185      * monitoring and operation management.

   186      *

   187      * @note Operations may also be other than just MNcdLoadNodeOperations.

   188      *

   189      * @return List of currently active operations for the node. Counted,

   190      *  each pointer must be released after use e.g. with a call to the array's

   191      *  RCatalogsArray::ResetAndDestroy().

   192      * @exception Leave System wide error code

   193      */

   194     virtual RCatalogsArray< MNcdOperation > OperationsL() const = 0;

   195     

   196     

   197     /**

   198      * Adds the node to favorite nodes. If the node is already

   199      * a favorite node, does nothing.

   200      *

   201      * @exception Leave System wide error code 

   202      */

   203     virtual void AddToFavoritesL() = 0;

   204         

   205     

   206 protected:

   207 

   208     /**

   209     * Destructor.

   210     *

   211     * @see MCatalogsBase::~MCatalogsBase

   212     */

   213     virtual ~MNcdNode() {}

   214     

   215     };

   216 

   217 

   218 #endif // M_NCD_NODE_H