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:  Manages data and access to the global chunk

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef MMPXDATA_H

    21 #define MMPXDATA_H

    22 

    23 // INCLUDES

    24 #include <mpxattribute.h>

    25 

    26 /**

    27  *  Base class for managing data in global heap.

    28  *

    29  *  @lib mpxcommon.lib

    30  */

    31 class MMPXData

    32     {

    33 public:

    34     /**

    35     * Defines 'markers' that identify objects from their streamed buffers, e.g.

    36     * if the first 4 bytes of an externalized object constitute the value EMedia,

    37     * then we assume the it is an externalized media object.

    38     */

    39     enum TMPXObjectType

    40         {

    41         EMedia=0x12343219,

    42         EMediaArray=0x987678ab,

    43         EPath=0x567982fe // Note: This can be removed when NO clients call

    44                          // CMPXMedia::Value API for CMPXCollectionPath.

    45         };

    46 public:

    47     /**

    48     * Create a new implementation of the MMPXData interface. This is thread-

    49     * relative.

    50     *

    51     * @since S60 3.2.3

    52     * @param aClientHandle client handle to the global chunk

    53     * @return pointer to the implementation object of MMXData

    54     */

    55     static MMPXData* NewL(TUint aClientHandle);

    56 

    57     /**

    58     * Create a new implementation from an existing MMPXData implementation.

    59     * This is an duplicate copy of the original.

    60     * This is thread-relative.

    61     *

    62     * @since S60 3.2.3

    63     * @param aClientHandle client handle to the global chunk

    64     * @param aData existing MMPXData implementation.

    65     * @return pointer to the implementation object of MMXData

    66     */

    67     static MMPXData* NewL(TUint aClientHandle,const MMPXData& aData);

    68 

    69     /**

    70     * Obtain the interface of an existing implementation from the handle.

    71     * This is thread-relative.

    72     *

    73     * @since S60 3.2.3

    74     * @param aClientHandle client handle to the global chunk

    75     * @param aDataHandle data handle to the MMPXData implementation.

    76     * @return pointer to the implementation object of MMXData

    77     */

    78     static MMPXData* Data(TUint aClientHandle,TUint aDataHandle);

    79 

    80     /**

    81     * Obtain the interface from a buffer, or NULL if the buffer does

    82     * not contain an implementation of the interface.

    83     *

    84     * @since S60 3.2.3

    85     * @param aClientHandle client handle to the global chunk

    86     * @param aData buffer which contains the object of MMPXData implementation

    87     * @return pointer to the implementation object of MMXData

    88     */

    89     static MMPXData* Data(TUint aClientHandle,const TDesC8& aData);

    90 

    91     /**

    92     * Obtains the interface from a buffer, or NULL if the buffer does

    93     * not contain an implementation of the interface.

    94     *

    95     * @since S60 3.2.3

    96     * @param aClientHandle client handle to the global chunk

    97     * @param aData buffer which contains the object of MMPXData implementation

    98     * @param aSize size of the data buffer

    99     * @return pointer to the implementation object of MMXData

   100     */

   101     static MMPXData* Data(TUint aClientHandle,TAny* aData,TInt aSize);

   102 

   103     /**

   104     * Handle which represents the current client (thread).

   105     * This should be stored by the client and provided in all methods;

   106     * zero indicates that it has failed.

   107     *

   108     * @since S60 3.2.3

   109     * @return Client handle of global chunk

   110     */

   111     static TUint ClientHandle();

   112 

   113     /**

   114     * To increment the reference count for this client (thread);

   115     * should be called for every media/media array object that

   116     * is not contained within another.

   117     *

   118     * @since S60 3.2.3

   119     * @param aClientHandle client handle to the global chunk

   120     */

   121     static void AddClientRef(TUint aClientHandle);

   122 

   123     /**

   124     * To decrement the reference count on this this client (thread).

   125     *

   126     * @since S60 3.2.3

   127     * @param aClientHandle client handle to the global chunk

   128     */

   129     static void ReleaseClient(TUint aClientHandle);

   130 

   131     /**

   132     * Gets the total size and the currently used size of the global heap.

   133     *

   134     * @since S60 3.2.3

   135     * @param aTotal Total size of memory (out parameter)

   136     * @param aUsed Used size of memory (out parameter)

   137     */

   138     static void HeapMemoryInfoL( TInt& aTotal, TInt& aUsed );

   139 

   140 

   141     /**

   142      * Lock the heap.

   143      *

   144      * @since S60 3.2.3

   145      * @param aClientHandle client handle to the global chunk

   146      */

   147     static void LockHeap(TUint aClientHandle);

   148 

   149     /**

   150      * Unlock the heap.

   151      *

   152      * @since S60 3.2.3

   153      * @param aClientHandle client handle to the global chunk

   154      */

   155     static void UnlockHeap(TUint aClientHandle);

   156 

   157 public:

   158     /**

   159     * Handle to the object implementing this interface; can

   160     * be used to reference the object.

   161     *

   162     * @since S60 3.2.3

   163     * @param aClientHandle client handle to the global chunk

   164     * @return data handle

   165     */

   166     virtual TUint DataHandle(TUint aClientHandle)=0;

   167 

   168     /**

   169     * To increment the reference count on this data.

   170     *

   171     * @since S60 3.2.3

   172     * @param aClientHandle client handle to the global chunk

   173     */

   174     virtual void AddRef(TUint aClientHandle)=0;

   175 

   176     /**

   177     * To decrement the reference count on this data; when zero,

   178     * the data is deleted.

   179     *

   180     * @since S60 3.2.3

   181     * @param aClientHandle client handle to the global chunk

   182     */

   183     virtual void Release(TUint aClientHandle)=0;

   184 

   185     /**

   186     * Gets the data value by index.

   187     *

   188     * @since S60 3.2.3

   189     * @param aClientHandle client handle to the global chunk

   190     * @param aIndex index of the data item

   191     * @return raw data

   192     */

   193     virtual TPtrC8 Value(TUint aClientHandle,TInt aIndex)=0;

   194 

   195     /**

   196      * Gets attribute by index.

   197      *

   198      * @since S60 3.2.3

   199      * @param aClientHandle client handle to the global chunk

   200      * @param aIndex index of the data item

   201      * @return attribute of the data

   202      */

   203     virtual const TMPXAttribute& Attribute(TUint aClientHandle,TInt aIndex)=0;

   204 

   205     /**

   206      * Gets object type by index.

   207      *

   208      * @since S60 3.2.3

   209      * @param aClientHandle client handle to the global chunk

   210      * @param aIndex index of the data item

   211      * @return object type of the data

   212      */

   213     virtual TMPXAttributeType AttributeType(TUint aClientHandle,TInt aIndex)=0;

   214 

   215     /**

   216      * Gets supported content ids.

   217      *

   218      * @since S60 3.2.3

   219      * @param aClientHandle client handle to the global chunk

   220      * @return array of supported content ids

   221      */

   222     virtual TArray<TInt> SupportedIds(TUint aClientHandle)=0;

   223 

   224     /**

   225      * Sets supported content ids.

   226      *

   227      * @since S60 3.2.3

   228      * @param aClientHandle client handle to the global chunk

   229      * @param aSupportedIds array of supported content ids

   230      * @return KErrNone if succeeded. Otheriwse system error code

   231      */

   232     virtual TInt SetSupportedIds(TUint aClientHandle,

   233                                  const TArray<TInt>& aSupportedIds)=0;

   234 

   235     /**

   236      * Delete a data item.

   237      *

   238      * @since S60 3.2.3

   239      * @param aClientHandle client handle to the global chunk

   240      * @param aIndex index of the data item

   241      */

   242     virtual void Delete(TUint aClientHandle,TInt aIndex)=0;

   243 

   244     /**

   245      * Set a data item.

   246      *

   247      * @since S60 3.2.3

   248      * @param aClientHandle client handle to the global chunk

   249      * @param aAttr media attribute

   250      * @param aType object type

   251      * @param aData raw data

   252      * @param aIndex index of the data item

   253      */

   254     virtual void Set(TUint aClientHandle,

   255                      const TMPXAttribute& aAttr,

   256                      TMPXAttributeType aType,

   257                      const TDesC8& aData,

   258                      TInt aIndex)=0;

   259 

   260     /**

   261      * Insert a data item.

   262      *

   263      * @since S60 3.2.3

   264      * @param aClientHandle client handle to the global chunk

   265      * @param aAttr media attribute

   266      * @param aType object type

   267      * @param aData raw data

   268      * @param aIndex index of the data item

   269      * @return KErrNone if succeeded. Otheriwse system error code

   270      */

   271     virtual TInt Insert(TUint aClientHandle,

   272                         const TMPXAttribute& aAttr,

   273                         TMPXAttributeType aType,

   274                         const TDesC8& aData,

   275                         TInt aIndex)=0;

   276 

   277     /**

   278      * Append a data item.

   279      *

   280      * @since S60 3.2.3

   281      * @param aClientHandle client handle to the global chunk

   282      * @param aAttr media attribute

   283      * @param aType object type

   284      * @param aData raw data

   285      * @return KErrNone if succeeded. Otheriwse system error code

   286      */

   287     virtual TInt Append(TUint aClientHandle,

   288                         const TMPXAttribute& aAttr,

   289                         TMPXAttributeType aType,

   290                         const TDesC8& aData)=0;

   291 

   292     /**

   293      * Remove all data items.

   294      *

   295      * @since S60 3.2.3

   296      * @param aClientHandle client handle to the global chunk

   297      */

   298     virtual void Reset(TUint aClientHandle)=0;

   299 

   300     /**

   301      * Returns number of data items.

   302      *

   303      * @since S60 3.2.3

   304      * @param aClientHandle client handle to the global chunk

   305      * @return number of data items.

   306      */

   307     virtual TInt Count(TUint aClientHandle)=0;

   308 

   309     /**

   310      * Returns index of the data item with the media attribute.

   311      *

   312      * @since S60 3.2.3

   313      * @param aClientHandle client handle to the global chunk

   314      * @param aAttr media attribute

   315      * @return index of the data items with the attribute

   316      */

   317     virtual TInt Index(TUint aClientHandle,const TMPXAttribute& aAttr)=0;

   318 

   319     /**

   320      * Returns index of the data item with aUid.

   321      *

   322      * @since S60 3.2.3

   323      * @param aClientHandle client handle to the global chunk

   324      * @param aUid uid of the data item

   325      * @return index of the data items with the attribute

   326      */

   327     virtual TInt Index(TUint aClientHandle,TInt aUid)=0;

   328 

   329     /**

   330      * Returns uid by index.

   331      *

   332      * @since S60 3.2.3

   333      * @param aClientHandle client handle to the global chunk

   334      * @param aIndex index of the data item

   335      * @return uid of the data item

   336      */

   337     virtual TInt Uid(TUint aClientHandle,TInt aIndex)=0;

   338     };

   339 

   340 #endif // MMPXDATA_H