--- /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 <e32std.h>
+
+// 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