diff -r f5050f1da672 -r 04becd199f91 javaextensions/pim/framework/inc.s60/cpimitemdata.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javaextensions/pim/framework/inc.s60/cpimitemdata.h Tue Apr 27 16:30:29 2010 +0300 @@ -0,0 +1,351 @@ +/* +* Copyright (c) 2008 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: Class for holding PIM item data + * +*/ + + +#ifndef CPIMITEMDATA_H +#define CPIMITEMDATA_H + +// INTERNAL INCLUDES +#include "mpimitemdata.h" + +// EXTERNAL INCLUDES +#include + +// FORWARD DECLARATIONS +class CPIMField; +class TPIMFieldData; + +/** + * This class representates one PIM item data. This is the actual + * storage class of the data values of one PIM fields. MPIMItemData + * is an interface which provides access to this class + * + * @since S60 v3.1 + */ +NONSHARABLE_CLASS(CPIMItemData) : public CBase, + public MPIMItemData +{ +public: + + /** + * Two-phased constructor. + * + * @return New instance of this class. + */ + static CPIMItemData* NewL(); + + /** + * Two-phased constructor. + * + * @return New instance of this class. The instance + * is pushed to the cleanup stack + */ + static CPIMItemData* NewLC(); + + /** + * Destructor + */ + virtual ~CPIMItemData(); + +public: // Methods from MPIMItemData + + /** + * Sets PIM field data with certain index + * + * This function is used to set all types of PIM + * data. The TPIMFieldData class encapsulates all + * possible data about one field so we don't need + * separate functions for each PIM field type + * + * @param aFieldData Reference to data class which + * all needed information about the new value + * + * @par Leaving + * @li KErrNotFound - The requested field has no value + */ + void SetValueL(const TPIMFieldData& aFieldData); + + /** + * Adds new PIM field data to certain field + * + * This function is used to add all types of PIM + * data. The TPIMFieldData class encapsulates all + * possible data about one field so we don't need + * separate functions for each PIM field type + * + * NOTE: The index value in the argument class is ignored + * + * @param aFieldData Reference to data class which + * all needed information about the new value + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + void AddValueL(const TPIMFieldData& aFieldData); + + /** + * Fetches value from specific value index. The value is + * capsulated inside TPIMFieldData class to ease an access + * to different types of values within the PIM item + * + * @param aIndex Index of the value in this specific field + * @return A class holding requested information + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + const TPIMFieldData ValueL(const TPIMField aField, + const TInt aIndex) const; + + /** + * Removes a specific value of a specific field. + * + * @param aIndex Index of the value that is to be removed. + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + void RemoveValueL(const TPIMField aField, + const TInt aIndex); + + /** + * Counts the number of values in a specific field. The values + * are counted as indexes within this field. If there is no requested + * field, this function returns zero + * + * @param aField The field values of which are to be counted. + * @return Number of values in field \a aField. + * Zero if there is no values + */ + TInt CountValues(const TPIMField aField) const; + + /** + * Returns an array of fields that currently have more than zero values + * The array is left to the cleanup stack + * + * @return Array of fields. The ownership of the array is transferred + * to the caller + */ + CArrayFix< TPIMField>* FieldsLC() const; + + /** + * Adds new label to an existing field + * + * @param aField Field to which the label is added + * @param aIndex Value index of the label + * @param aArrayIndex Array index of the label + * @param aLabel New label + */ + void SetLabelL( + const TPIMField aField, + const TInt aIndex, + const TInt aArrayIndex, + const TDesC& aLabel); + + /** + * Retrieves the label from the specific field with specific + * field and array indexes. + * + * @param aField Field from which the label is retrieved + * @param aIndex Index of the field's value + * @param aArrayIndex Index of the array index if this is a string + * array field + * + * @return Label name + */ + const TPtrC LabelL( + const TPIMField aField, + const TInt aIndex, + const TInt aArrayIndex) const; + + /** + * Clears all fields from this item data. + */ + void Reset(); + + /** + * Sets new attributes for a specific field and value index + * + * @param aField Field for which the attributes are to be added + * @param aIndex Index of the value in this specific field + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + void SetAttributesL( + const TPIMField aField, + const TInt aIndex, + TPIMAttribute aAttributes); + + /** + * Retrieves attributes from an index within a field + * + * @param aField Field from which the attributes are to fetched + * @param aIndex Value index of the field + * @return Attributes of this value index + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + TInt AttributesL( + const TPIMField aField, + const TInt aIndex) const; + + /** + * Sets internal attributes to an index within a field. + * Internal attributes are not accessible from the Java-side + * so this function provides only access to set internal + * attributes + * + * @param aField Field from which the attributes are to fetched + * @param aIndex Value index of the field + * @param aInternalAttributes New internal attributes. Old ones + * will be overwriten + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + void SetInternalAttributesL( + const TPIMField aField, + const TInt aIndex, + CArrayFix< TUid>* aInternalAttributes); + + /** + * Retrieves internal attributes from an index within a field. + * Internal attributes are not accessible from the Java-side + * so this function provides only access to retrieve internal + * attributes + * + * @param aField Field from which the attributes are to fetched + * @param aIndex Value index of the field + * + * @return Internal attributes of this value index + * + * @par Leaving: + * The method leaves on error. Error codes are interpreted as follows: + * @li \c KErrNotFound - There is not value for given \a aIndex. + * @li Other - The value could not be removed cleanly. This probably + * means that the value array has gone corrupt. + */ + const CArrayFix< TUid>& InternalAttributesL( + const TPIMField aField, + const TInt aIndex) const; + + /** + * FindCategory + * Finds a category from the category list + * If the requested category was not found, KErrNotFound is + * returned + * + * @param aCategoryName Category name to find + * @return If found, the index of the category and KErrNotFound + * if the category was not found + */ + TInt FindCategory(const TDesC& aCategoryName) const; + + /** + * AddNewCategoryL + * Adds new category to the category list + * + * @param aCategoryName Category name which is to be added + */ + void AddNewCategoryL(const TDesC& aCategoryName); + + /** + * RemoveCategory + * Removes a category from the category list + * Returns ETrue if the category was found and removed + * and EFalse if there was no such category + * + * @param aCategoryName Category name which is to be removed + * @return ETrue if the category was removed, EFalse if not + */ + TBool RemoveCategory(const TDesC& aCategoryName); + + /** + * Categories + * Returns a reference to the categories associeated + * with this item data + * + * @return A reference to the list of categories + */ + const CDesCArray& Categories() const; + +public: // New functions + + /** + * Check if this item data contains requested field + * @param aField Field which is to be checked + * @return ETrue if the field is present, EFalse if not + */ + TBool HasField(const TPIMField aField) const; + +private: + + /** + * C++ default constructor + */ + inline CPIMItemData(); + + /** + * Seconds phase constructor + */ + inline void ConstructL(); + +private: // New functions + + /** + * Finds index of the requested field if it is in the + * field array + * + * @param aField requested field + * + * @return Index of the field. If not found, KErrNotFound + * is returned + */ + TInt FieldIndex(const TPIMField aField) const; + +private: // Data + + /** PIM field array */ + RPointerArray< CPIMField> iFields; + + /** Categories associated with this item data. Owned */ + CDesCArray* iCategories; + +}; + +#endif // CPIMITEMDATA_H +// End of file