/*
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Encapsulates array of media objects
*
*/
#ifndef CMPXMEDIAARRAY_H
#define CMPXMEDIAARRAY_H
#include "mpxmediabase.h"
class CMPXMedia;
/**
* Array of media objects.
*
* @lib mpxcommon.lib
*/
class CMPXMediaArray : public CMPXMediaBase
{
public:
/**
* Two-phased constructor.
*
* @since S60 3.2.3
* @return new instance of object
*/
IMPORT_C static CMPXMediaArray* NewL();
/**
* Two-phased constructor.
*
* @since S60 3.2.3
* @param aArray array to copy
* @return new instance of object
*/
IMPORT_C static CMPXMediaArray* NewL(const CMPXMediaArray& aArray);
/**
* Destructor.
*
* @since S60 3.2.3
*/
IMPORT_C ~CMPXMediaArray();
/**
* Total number of objects contained in array.
*
* @since S60 3.2.3
* @return number of contained media objects
*/
IMPORT_C TInt Count() const;
/**
* Array assessor.
* This method returns NULL if local heap is out of memory. Clients should
* check returned pointer before using it.
*
* @since S60 3.2.3
* @param aIndex index into the array
* @return media object at index, ownership not transferred
*/
IMPORT_C CMPXMedia* operator[](TInt aIndex) const;
/**
* Get a pointer to the media object at the specified position within the array.
*
* @since S60 3.2.3
* @param aIndex index into the array
* @leave KErrNoMemory if local heap is out of memory or other system error.
* @assert User 0 is the aIndex is out of bound
* @return media object at index, ownership not transferred
*/
IMPORT_C CMPXMedia* AtL(TInt aIndex) const;
/**
* Appends media object to array.
* Note: Ownership of aMedia transferred.
*
* @since S60 3.2.3
* @param aMedia object to add to the array
*/
IMPORT_C void AppendL(const CMPXMedia* aMedia);
/**
* Appends media object to array.
* A new media object will be copied from aMedia. The new media object
* created on global heap and added into the array.
*
* @since S60 3.2.3
* @param aMedia object to add to the array
*/
IMPORT_C void AppendL(const CMPXMedia& aMedia);
/**
* Resets the media array.
*
* @since S60 3.2.3
*/
IMPORT_C void Reset();
/**
* Removes the object pointer at the specified
* position from the array and deletes the
* object whose pointer is removed.
*
* @since S60 3.2.3
* @param aIndex The position within the array
* from where the object pointer is to be
* removed. The position is relative to
* zero, i.e. zero implies that a pointer
* at the beginning of the array is to be
* removed.
*/
IMPORT_C void Remove(TInt aIndex);
/**
* Inserts the object pointer into the array at
* the specified position.
* Note: Ownership of aMedia transferred.
*
* @since S60 3.2.3
* @param aMedia object to be inserted to the
* array
* @param aPos the position within the array
* where the object pointer is to be inserted.
* The position is relative to zero, i.e.
* zero implies that a pointer is inserted
* at the beginning of the array.
* USER 131, if aPos is negative, or is
* greater than the number of object
* pointers currently in the array.
* @return KErrNone, if the insertion is
* successful, otherwise one of the system
* wide error codes.
* @leave The function leaves with one of the system wide error codes,
*/
IMPORT_C TInt Insert(const CMPXMedia *aMedia, TInt aPos);
/**
* Inserts the object pointer into the array at
* the specified position.
* A new media object will be copied from aMedia. The new media object
* created on global heap and added into the array.
*
* @since S60 3.2.3
* @param aMedia object to be inserted to the
* array
* @param aPos the position within the array
* where the object pointer is to be inserted.
* The position is relative to zero, i.e.
* zero implies that a pointer is inserted
* at the beginning of the array.
* USER 131, if aPos is negative, or is
* greater than the number of object
* pointers currently in the array.
* @return KErrNone, if the insertion is
* successful, otherwise one of the system
* wide error codes.
* @leave The function leaves with one of the system wide error codes,
*/
IMPORT_C TInt Insert(const CMPXMedia& aMedia, TInt aPos);
/**
* Inserts the object pointer into the array at
* the specified position. The function leaves
* with one of the system wide error codes, if
* the operation fails.
* Note: Ownership of aMedia transferred.
*
* @since S60 3.2.3
* @param aMedia object to be inserted to the
* array
* @param aPos the position within the array
* where the object pointer is to be inserted.
* The position is relative to zero, i.e.
* zero implies that a pointer is inserted
* at the beginning of the array.
* USER 131, if aPos is negative, or is
* greater than the number of object
* pointers currently in the array.
*/
IMPORT_C void InsertL(const CMPXMedia *aMedia, TInt aPos);
/**
* Inserts the object pointer into the array at
* the specified position. The function leaves
* with one of the system wide error codes, if
* the operation fails.
* A new media object will be copied from aMedia. The new media object
* created on global heap and added into the array.
*
* @since S60 3.2.3
* @param aMedia object to be inserted to the
* array
* @param aPos the position within the array
* where the object pointer is to be inserted.
* The position is relative to zero, i.e.
* zero implies that a pointer is inserted
* at the beginning of the array.
* USER 131, if aPos is negative, or is
* greater than the number of object
* pointers currently in the array.
*/
IMPORT_C void InsertL(const CMPXMedia& aMedia, TInt aPos);
/**
* Sets the value at a specified position; the previous
* value is deleted.
*
* @since S60 3.2.3
* @param aMedia object to be set to the
* array
* @param aPos the position within the array
* where the object pointer is to be set.
* The position is relative to zero, i.e.
* zero implies that a pointer is inserted
* at the beginning of the array.
* USER 131, if aPos is negative, or is
* greater than the number of objects
* currently in the array.
*/
IMPORT_C void Set(const CMPXMedia& aMedia, TInt aPos);
public:
/**
* Externalize media objects.
* @since S60 3.2.3
* @param aStream write stream
*/
IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
/**
* Internalize media objects.
*
* @since S60 3.2.3
* @param aStream read stream
*/
IMPORT_C void InternalizeL(RReadStream& aStream);
private:
/**
* Value at a specific index.
*
* @since S60 3.2.3
*/
CMPXMedia* Value(TInt aIndex) const;
/**
* Value at a specific index.
*
* @since S60 3.2.3
*/
CMPXMedia* ValueL(TInt aIndex) const;
/**
* Inserts/Updates a value at aPos.
*
* @since S60 3.2.3
*/
TInt AddToArray(const CMPXMedia& aMedia,TInt aPos,TBool aReplace=EFalse);
};
#endif // CMPXMEDIAARRAY_H