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:  Encapsulates array of media objects

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CMPXMEDIAARRAY_H

    21 #define CMPXMEDIAARRAY_H

    22 

    23 

    24 #include "mpxmediabase.h"

    25 

    26 class CMPXMedia;

    27 

    28 /**

    29 *  Array of media objects.

    30 *

    31 *  @lib mpxcommon.lib

    32 */

    33 class CMPXMediaArray : public CMPXMediaBase

    34     {

    35 public:

    36 

    37     /**

    38     * Two-phased constructor.

    39     *

    40     * @since S60 3.2.3

    41     * @return new instance of object

    42     */

    43     IMPORT_C static CMPXMediaArray* NewL();

    44 

    45     /**

    46     * Two-phased constructor.

    47     *

    48     * @since S60 3.2.3

    49     * @param aArray array to copy

    50     * @return new instance of object

    51     */

    52     IMPORT_C static CMPXMediaArray* NewL(const CMPXMediaArray& aArray);

    53 

    54     /**

    55     *  Destructor.

    56     *

    57     *  @since S60 3.2.3

    58     */

    59     IMPORT_C ~CMPXMediaArray();

    60 

    61     /**

    62     *  Total number of objects contained in array.

    63     *

    64     *  @since S60 3.2.3

    65     *  @return number of contained media objects

    66     */

    67     IMPORT_C TInt Count() const;

    68 

    69     /**

    70     *  Array assessor.

    71     *  This method returns NULL if local heap is out of memory. Clients should

    72     *  check returned pointer before using it.

    73     *

    74     *  @since S60 3.2.3

    75     *  @param aIndex index into the array

    76     *  @return media object at index, ownership not transferred

    77     */

    78     IMPORT_C CMPXMedia* operator[](TInt aIndex) const;

    79 

    80     /**

    81     *  Get a pointer to the media object at the specified position within the array.

    82     *

    83     *  @since S60 3.2.3

    84     *  @param aIndex index into the array

    85     *  @leave KErrNoMemory if local heap is out of memory or other system error.

    86     *  @assert User 0 is the aIndex is out of bound

    87     *  @return media object at index, ownership not transferred

    88     */

    89     IMPORT_C CMPXMedia* AtL(TInt aIndex) const;

    90 

    91     /**

    92     *  Appends media object to array.

    93     *  Note: Ownership of aMedia transferred.

    94     *

    95     *  @since S60 3.2.3

    96     *  @param aMedia object to add to the array

    97     */

    98     IMPORT_C void AppendL(const CMPXMedia* aMedia);

    99 

   100     /**

   101     *  Appends media object to array.

   102     *  A new media object will be copied from aMedia. The new media object

   103     *  created on global heap and added into the array.

   104     *

   105     *  @since S60 3.2.3

   106     *  @param aMedia object to add to the array

   107     */

   108     IMPORT_C void AppendL(const CMPXMedia& aMedia);

   109 

   110     /**

   111     *  Resets the media array.

   112     *

   113     *  @since S60 3.2.3

   114     */

   115     IMPORT_C void Reset();

   116 

   117     /**

   118     * Removes the object pointer at the specified

   119     * position from the array and deletes the

   120     * object whose pointer is removed.

   121     *

   122     * @since S60 3.2.3

   123     * @param aIndex The position within the array

   124     *        from where the object pointer is to be

   125     *        removed. The position is relative to

   126     *        zero, i.e. zero implies that a pointer

   127     *        at the beginning of the array is to be

   128     *        removed.

   129     */

   130     IMPORT_C void Remove(TInt aIndex);

   131 

   132     /**

   133     * Inserts the object pointer into the array at

   134     * the specified position.

   135     * Note: Ownership of aMedia transferred.

   136     *

   137     * @since S60 3.2.3

   138     * @param aMedia object to be inserted to the

   139     *        array

   140     * @param aPos the position within the array

   141     *        where the object pointer is to be inserted.

   142     *        The position is relative to zero, i.e.

   143     *        zero implies that a pointer is inserted

   144     *        at the beginning of the array.

   145     *        USER 131, if aPos is negative, or is

   146     *        greater than the number of object

   147     *        pointers currently in the array.

   148     * @return KErrNone, if the insertion is

   149     *        successful, otherwise one of the system

   150     *        wide error codes.

   151     * @leave The function leaves with one of the system wide error codes,

   152     */

   153     IMPORT_C TInt Insert(const CMPXMedia *aMedia, TInt aPos);

   154 

   155     /**

   156     * Inserts the object pointer into the array at

   157     * the specified position.

   158     * A new media object will be copied from aMedia. The new media object

   159     * created on global heap and added into the array.

   160     *

   161     * @since S60 3.2.3

   162     * @param aMedia object to be inserted to the

   163     *        array

   164     * @param aPos the position within the array

   165     *        where the object pointer is to be inserted.

   166     *        The position is relative to zero, i.e.

   167     *        zero implies that a pointer is inserted

   168     *        at the beginning of the array.

   169     *        USER 131, if aPos is negative, or is

   170     *        greater than the number of object

   171     *        pointers currently in the array.

   172     * @return KErrNone, if the insertion is

   173     *        successful, otherwise one of the system

   174     *        wide error codes.

   175     * @leave The function leaves with one of the system wide error codes,

   176     */

   177     IMPORT_C TInt Insert(const CMPXMedia& aMedia, TInt aPos);

   178 

   179     /**

   180     * Inserts the object pointer into the array at

   181     * the specified position. The function leaves

   182     * with one of the system wide error codes, if

   183     * the operation fails.

   184     * Note: Ownership of aMedia transferred.

   185     *

   186     * @since S60 3.2.3

   187     * @param aMedia object to be inserted to the

   188     *        array

   189     * @param aPos the position within the array

   190     *        where the object pointer is to be inserted.

   191     *        The position is relative to zero, i.e.

   192     *        zero implies that a pointer is inserted

   193     *        at the beginning of the array.

   194     *        USER 131, if aPos is negative, or is

   195     *        greater than the number of object

   196     *        pointers currently in the array.

   197     */

   198     IMPORT_C void InsertL(const CMPXMedia *aMedia, TInt aPos);

   199 

   200     /**

   201     * Inserts the object pointer into the array at

   202     * the specified position. The function leaves

   203     * with one of the system wide error codes, if

   204     * the operation fails.

   205     * A new media object will be copied from aMedia. The new media object

   206     * created on global heap and added into the array.

   207     *

   208     * @since S60 3.2.3

   209     * @param aMedia object to be inserted to the

   210     *        array

   211     * @param aPos the position within the array

   212     *        where the object pointer is to be inserted.

   213     *        The position is relative to zero, i.e.

   214     *        zero implies that a pointer is inserted

   215     *        at the beginning of the array.

   216     *        USER 131, if aPos is negative, or is

   217     *        greater than the number of object

   218     *        pointers currently in the array.

   219     */

   220     IMPORT_C void InsertL(const CMPXMedia& aMedia, TInt aPos);

   221 

   222     /**

   223     * Sets the value at a specified position; the previous

   224     * value is deleted.

   225     *

   226     * @since S60 3.2.3

   227     * @param aMedia object to be set to the

   228     *        array

   229     * @param aPos the position within the array

   230     *        where the object pointer is to be set.

   231     *        The position is relative to zero, i.e.

   232     *        zero implies that a pointer is inserted

   233     *        at the beginning of the array.

   234     *        USER 131, if aPos is negative, or is

   235     *        greater than the number of objects

   236     *        currently in the array.

   237     */

   238     IMPORT_C void Set(const CMPXMedia& aMedia, TInt aPos);

   239 

   240 public:

   241     /**

   242     * Externalize media objects.

   243     * @since S60 3.2.3

   244     * @param aStream write stream

   245     */

   246     IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   247 

   248     /**

   249     * Internalize media objects.

   250     *

   251     * @since S60 3.2.3

   252     * @param aStream read stream

   253     */

   254     IMPORT_C void InternalizeL(RReadStream& aStream);

   255 

   256 private:

   257     /**

   258     *  Value at a specific index.

   259     *

   260     *  @since S60 3.2.3

   261     */

   262     CMPXMedia* Value(TInt aIndex) const;

   263 

   264     /**

   265     *  Value at a specific index.

   266     *

   267     *  @since S60 3.2.3

   268     */

   269     CMPXMedia* ValueL(TInt aIndex) const;

   270 

   271     /**

   272     *  Inserts/Updates a value at aPos.

   273     *

   274     *  @since S60 3.2.3

   275     */

   276     TInt AddToArray(const CMPXMedia& aMedia,TInt aPos,TBool aReplace=EFalse);

   277     };

   278 

   279 #endif // CMPXMEDIAARRAY_H