--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javaextensions/pim/common/inc.s60/mpimitem.h Tue Apr 27 16:30:29 2010 +0300
@@ -0,0 +1,596 @@
+/*
+* 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: Access interface to PIM item common data representation.
+ *
+*/
+
+
+#ifndef MPIMITEM_H
+#define MPIMITEM_H
+
+// INCLUDES
+#include "pimcommon.h"
+#include "bamdesca.h" // For MDesCArray
+#include "badesca.h" // For CDesCArray
+/**
+ * Interface for manipulating item data in the Framework.
+ * The interface does
+ * as few checks as possible to provide "raw" access to the data in a
+ * list-independent manner.
+ *
+ * Only CBase-derived classes may implement this interface. Deriving other
+ * M-classes from this class is \b prohibited. Deriving specialized M-classes
+ * from this class might result in a "diamond-shaped" inheritance tree,
+ * because it is intended that the common parts of the item implementation
+ * implement this interface. Specialized implementations will be derived
+ * from that common implementation and those must implement the specialized
+ * interfaces (M-classes), too. Diamond-shaped inheritance is highly
+ * discouraged in Symbian OS. The case is resolved so that the M-classes
+ * that would be derived from this class provide a \e getter method, say
+ * \c "GetItemData()", that returns a pointer to this interface. The two
+ * interfaces access the same object, thus providing an "inheritance-like"
+ * accessibility to that object.
+ *
+ * When accessing data through this interface, the following things are
+ * checked:
+ * @li Field validity in accordance to the PIM type (Contact, Event, ToDo).
+ * No fields belonging to different PIM type are allowed to be manipulated
+ * through this interface.
+ * @li Field value validity in accordance to the field value type (binary,
+ * boolean, integer, ...). Value types do not mix.
+ * @li Existence of a requested value for given field and index in the value
+ * array when getting a value.
+ * @li Is a field supported by a specific list (adapter) implementation, if
+ * the item belongs to a list.
+ * @li Is an attribute valid for a specific field.
+ * @li Is an attribute supported by a specific list (adapter) implementation,
+ * if the item belongs to a list.
+ * @li Value array maximum sizes, if the item belongs to a list.
+ *
+ * NOTE: If you use PIM item via this interface, be sure that when modifiying
+ * non-initialized fields with huge amount if item may cause significant
+ * overhead if the data is not available.
+ */
+NONSHARABLE_CLASS(MPIMItem)
+{
+public: // Destructor
+
+ /**
+ * Destructor.
+ */
+ virtual ~MPIMItem()
+ {}
+
+public: // New functions
+
+ /**
+ * Provides all fields that have values in the item.
+ *
+ * @return An array of fields. The \b ownership of the array is
+ * transferred to the caller. The order of fields is
+ * undefined.
+ *
+ * @par Leaving:
+ * The method leaves on error.
+ */
+ virtual CArrayFix< TPIMField>* GetFieldsL() const = 0;
+
+ /* --- Binary --- */
+
+ /**
+ * Gets specific binary value.
+ * The value is Base64-encoded.
+ *
+ * @param aField Field constant.
+ * @param aIndex Value index.
+ * @return Byte array value.
+ * \b Ownership of the return value is transferred to caller.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is no value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual CPIMByteArray* GetBinaryL(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Same as GetBinaryL, but provides the value non-Base64-encoded.
+ * Ownership of the return value remains.
+ */
+ virtual const CPIMByteArray
+ & GetBinaryRawL(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Adds a binary value for a binary field. The value is added as the
+ * last value in that field's value array.
+ * The value must be Base64-encoded.
+ *
+ * @param aField The field to which the value is added.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The binary value to be added to the field.
+ * \b Ownership of the value is transferred to the called
+ * object.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type or \a aValue is NULL.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrOverflow - The field already contains the maximum
+ * number of values it can hold.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be added.
+ */
+ virtual void AddBinaryL(TPIMField aField, TPIMAttribute aAttributes,
+ CPIMByteArray* aValue) = 0;
+
+ /**
+ * Same as AddBinaryL, but takes the value non-Base64-encoded.
+ */
+ virtual void AddBinaryRawL(TPIMField aField, TPIMAttribute aAttributes,
+ CPIMByteArray* aValue) = 0;
+
+ /**
+ * Sets an existing binary value, discarding the old value.
+ * The value must be Base64-encoded.
+ *
+ * @param aField The field for which the value is set.
+ * @param aIndex The index of the value in the value array.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The value to be set in the place of the old value.
+ * \b Ownership of the new value is transferred to the called
+ * object. The old value is deleted.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type or \a aValue is NULL.
+ * @li \c KErrNotFound - There is not value for given \a aIndex.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be set.
+ */
+ virtual void SetBinaryL(TPIMField aField, TInt aIndex,
+ TPIMAttribute aAttributes, CPIMByteArray* aValue) = 0;
+
+ /**
+ * Same as SetBinaryL, but takes the value non-Base64-encoded.
+ */
+ virtual void SetBinaryRawL(TPIMField aField, TInt aIndex,
+ TPIMAttribute aAttributes, CPIMByteArray* aValue) = 0;
+
+ /* --- Date --- */
+
+ /**
+ * Gets specific date value.
+ *
+ * @param aField Field constant.
+ * @param aIndex Value index.
+ * @return Date value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is no value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual const TPIMDate GetDateL(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Adds a date value for a date field. The value is added as the
+ * last value in that field's value array.
+ *
+ * @param aField The field to which the value is added.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The date value to be added to the field.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrOverflow - The field already contains the maximum
+ * number of values it can hold.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be added.
+ */
+ virtual void AddDateL(TPIMField aField, TPIMAttribute aAttributes,
+ TPIMDate aValue) = 0;
+
+ /**
+ * Sets an existing date value, discarding the old value.
+ *
+ * @param aField The field for which the value is set.
+ * @param aIndex The index of the value in the value array.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The value to be set in the place of the old value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is not value for given \a aIndex.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be set.
+ */
+ virtual void SetDateL(TPIMField aField, TInt aIndex,
+ TPIMAttribute aAttributes, TPIMDate aValue) = 0;
+
+ /* --- Int --- */
+
+ /**
+ * Gets specific int value.
+ *
+ * @param aField Field constant.
+ * @param aIndex Value index.
+ * @return Integer value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is no value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual int getInt(TPIMField aField, int aIndex) const = 0;
+
+
+ /* --- String --- */
+
+ /**
+ * Gets specific string value.
+ *
+ * @param aField Field constant.
+ * @param aIndex Value index.
+ * @return String value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is no value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual const TDesC& GetStringL(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Adds a string value for a string field. The value is added as the
+ * last value in that field's value array.
+ *
+ * @param aField The field to which the value is added.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The string value to be added to the field.
+ * \b Ownership of the value is transferred to the called
+ * object.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type or \a aValue is NULL.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrOverflow - The field already contains the maximum
+ * number of values it can hold.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be added.
+ */
+ virtual void AddStringL(TPIMField aField, TPIMAttribute aAttributes,
+ HBufC* aValue) = 0;
+
+ /**
+ * Sets an existing string value, discarding the old value.
+ *
+ * @param aField The field for which the value is set.
+ * @param aIndex The index of the value in the value array.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The value to be set in the place of the old value.
+ * \b Ownership of the value is transferred to the called
+ * object. The old value is deleted.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type or \a aValue is NULL.
+ * @li \c KErrNotFound - There is not value for given \a aIndex.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be set.
+ */
+ virtual void SetStringL(TPIMField aField, TInt aIndex,
+ TPIMAttribute aAttributes, HBufC* aValue) = 0;
+
+ /* --- Boolean --- */
+
+ /**
+ * Gets specific boolean value.
+ *
+ * @param aField Field constant.
+ * @param aIndex Value index.
+ * @return Boolean value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is no value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual TBool GetBooleanL(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Adds a boolean value for a boolean field. The value is added as the
+ * last value in that field's value array.
+ *
+ * @param aField The field to which the value is added.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The boolean value to be added to the field.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrOverflow - The field already contains the maximum
+ * number of values it can hold.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be added.
+ */
+ virtual void AddBooleanL(TPIMField aField, TPIMAttribute aAttributes,
+ TBool aValue) = 0;
+
+ /**
+ * Sets an existing boolean value, discarding the old value.
+ *
+ * @param aField The field for which the value is set.
+ * @param aIndex The index of the value in the value array.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The value to be set in the place of the old value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is not value for given \a aIndex.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be set.
+ */
+ virtual void SetBooleanL(TPIMField aField, TInt aIndex,
+ TPIMAttribute aAttributes, TBool aValue) = 0;
+
+ /* --- StringArray --- */
+
+ /**
+ * Gets specific string array value.
+ * Empty string array elements are denoted with an empty string.
+ *
+ * @param aField Field constant.
+ * @param aIndex Value index.
+ * @return StringArray value.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is no value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual const CDesCArray
+ & GetStringArrayL(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Adds a string array value for a string array field.
+ * The value is added as the last value in that field's value array.
+ * All elements of the string array must be present in their specified
+ * indexes. Empty elements are denoted with an empty string.
+ *
+ * @param aField The field to which the value is added.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The string array value to be added to the field.
+ * \b Ownership of the value is transferred to the called
+ * object.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type or \a aValue is NULL.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrOverflow - The field already contains the maximum
+ * number of values it can hold.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be added.
+ */
+ virtual void AddStringArrayL(TPIMField aField, TPIMAttribute aAttributes,
+ CDesCArray* aValue) = 0;
+
+ /**
+ * Sets an existing string array value, discarding the old value.
+ * All elements of the string array must be present in their specified
+ * indexes. Empty elements are denoted with an empty string.
+ *
+ * @param aField The field for which the value is set.
+ * @param aIndex The index of the value in the value array.
+ * @param aAttributes The attributes to be set for the value.
+ * @param aValue The value to be set in the place of the old value.
+ * \b Ownership of the value is transferred to the called
+ * object. The old value is deleted.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type or \a aValue is NULL.
+ * @li \c KErrNotFound - There is not value for given \a aIndex.
+ * @li \c KErrTooBig - \a aValue is not valid for the field.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ * @li \c KErrLocked - \a aField is read-only.
+ * @li Other - The value could not be set.
+ */
+ virtual void SetStringArrayL(TPIMField aField, TInt aIndex,
+ TPIMAttribute aAttributes, CDesCArray* aValue) = 0;
+
+ /**
+ * Counts the number of values in a specific field.
+ *
+ * @param aField The field values of which are to be counted.
+ *
+ * @return Number of values in field \a aField.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual TInt CountValuesL(TPIMField aField) const = 0;
+
+
+ /**
+ * Provides attributes of a specific value of a specific field.
+ *
+ * @param aField The field that has the value.
+ * @param aIndex The index of the value in the value array.
+ *
+ * @return The attributes set for the value, orred bitwise.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aField is not valid for the implementing
+ * PIM item type.
+ * @li \c KErrNotFound - There is not value for given \a aIndex.
+ * @li \c KErrNotSupported - The item is associated with a list and
+ * The list does not support \a aField.
+ */
+ virtual TPIMAttribute
+ getAttributes(TPIMField aField, TInt aIndex) const = 0;
+
+ /**
+ * Adds the item to a category.
+ * If the item already belongs to the category, nothing is done.
+ *
+ * @param aCategory The category. Category name is copied if necessary.
+ *
+ * @par Leaving:
+ * The method leaves on error. Error codes should be interpreted as
+ * follows:
+ * @li \c KErrArgument - \a aCategory is not valid for the item.
+ * @li Other - The item could not be added to the category for some
+ * internal reason.
+ */
+ virtual void AddToCategoryL(const TDesC& aCategory) = 0;
+
+ /**
+ * Removes the item from a category.
+ * If the item does not belong to the category, nothing is done.
+ *
+ * @param aCategory. The category.
+ *
+ */
+ virtual void RemoveFromCategory(const TDesC& aCategory) = 0;
+
+ /**
+ * Provides the categories to which the item belongs to.
+ *
+ * @return Array of categories.
+ *
+ * @par Leaving:
+ * The method leaves on error.
+ */
+ virtual const CDesCArray& GetCategoriesL() const = 0;
+
+ /**
+ * Provides the Item ID of the item.
+ *
+ * @return Item ID. If the Item ID is not set, \ref KPIMNullItemID is
+ * returned.
+ */
+ virtual TPIMItemID GetId() const = 0;
+
+ /**
+ * Sets the Item ID of the item.
+ *
+ * @param aItemID The new Item ID.
+ *
+ * @par Leaving:
+ * @li Any - An internal error.
+ */
+ virtual void SetIdL(TPIMItemID aItemID) = 0;
+
+ /**
+ * Sets the last modified date/time of the item.
+ */
+ virtual void SetLastModifiedL(TPIMDate aLastModified) = 0;
+
+ /**
+ * Gets the last modified date/time of the item.
+ */
+ virtual TPIMDate LastModified() const = 0;
+
+protected: // Non-public operations
+
+ // Allow derivation with protected default constructor.
+ MPIMItem()
+ {}
+
+}
+;
+
+#endif // MPIMITEM_H
+// End of File