diff -r f5050f1da672 -r 04becd199f91 javaextensions/pim/framework/inc.s60/cpimfield.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javaextensions/pim/framework/inc.s60/cpimfield.h Tue Apr 27 16:30:29 2010 +0300 @@ -0,0 +1,294 @@ +/* +* 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 field data + * +*/ + + +#ifndef CPIMFIELD_H +#define CPIMFIELD_H + +// INTERNAL INCLUDES +#include "tpimfielddata.h" + +// EXTERNAL INCLUDES +#include + +// FORWARD DECLARATIONS +class CPIMValueBase; + +/** + * Class for holding PIM field data. This class + * stores value indexes to an array. + * @since S60 v3.1 + */ +NONSHARABLE_CLASS(CPIMField) : public CBase +{ +public: + + /** + * Two-phased constructor. + * + * @return New instance of this class. + */ + static CPIMField* NewL(const TPIMFieldData& aFieldData); + + /** + * Two-phased constructor. + * + * @return New instance of this class. The instance + * is pushed to the cleanup stack + */ + static CPIMField* NewLC(const TPIMFieldData& aFieldData); + + /** + * Destructor + */ + virtual ~CPIMField(); + +public: // New methods + + /** + * 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: + * 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 or OOM situation + * has occured + */ + 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 or OOM situation + * has occured + */ + void AddValueL(const TPIMFieldData& aFieldData); + + /** + * Fetches value from specific value index. + * + * @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 or OOM situation + * has occured + */ + const TPIMFieldData ValueL(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 or OOM situation + * has occured + */ + void RemoveValueL(const TInt aIndex); + + /** + * Count values currently in this PIM field + * + * @return Number of values in this field + */ + TInt CountValues() const; + + /** + * Adds new label to an existing field + * + * @param aIndex Value index of the label + * @param aArrayIndex Array index of the label + * @param aLabel New label + * + * @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 or OOM situation + * has occured + */ + void SetLabelL( + const TInt aIndex, + const TInt aArrayIndex, + const TDesC& aLabel); + + /** + * Retrieves the label from the specific field with specific + * field and array indexes. + * + * @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. NULL if there is no label for this array + * index or the labels have not been allocated yet + */ + const TPtrC Label( + const TInt aIndex, + const TInt aArrayIndex) const; + + /** + * DataType + * Returns the data type of this PIM field + * + * @return Data type of this field + */ + TPIMFieldDataType DataType() const; + + /** + * FieldType + * Returns the type of this field + * + * @return The type of this field + */ + TPIMField FieldType() const; + + /** + * SetAttributesL + * Sets new attributes for a specific value + * + * @param aIndex Index of the value + * @param aAttributes New attributes + * + * @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 or OOM situation + * has occured + */ + void SetAttributesL(const TInt aIndex, TPIMAttribute aAttributes); + + /** + * AttributesL + * Returns attributes from the specific value + * + * @param aIndex Index of the value + * @return Attributes of the 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 or OOM situation + * has occured + */ + TPIMAttribute AttributesL(const TInt aIndex) const; + + /** + * SetInternalAttributesL + * Sets new internal attributes for a specific value. NOTE: + * Internal attributes are not accessible from the Java-side + * They only store information which must be preserved when item + * is loaded from the native database and modified before storing + * + * @param aIndex Index of the value + * @param aAttributes New attributes + * + * @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 or OOM situation + * has occured + */ + void SetInternalAttributesL( + const TInt aIndex, + CArrayFix< TUid>* aInternalAttributes); + + /** + * InternalAttributesL + * Returns internal attributes from the specific value. NOTE: + * Internal attributes are not accessible from the Java-side + * They only store information which must be preserved when item + * is loaded from the native database and modified before storing + * + * @param aIndex Index of the value + * @return Attributes of the 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 or OOM situation + * has occured + */ + const CArrayFix< TUid>& InternalAttributesL(const TInt aIndex) const; + +private: // New methods + + /** + * Checks that the given index is in the value + * range. + * + * @param aIndex Index which is to be checked + * @return ETrue if the index is in range, EFalse if not + */ + TBool IsInRange(const TInt aIndex) const; + +private: + + /** + * C++ default constructor + */ + inline CPIMField(const TPIMFieldData& aFieldData); + +private: // Data + + /** Type of this field */ + TPIMField iField; + + /** Data type of this field */ + TPIMFieldDataType iFieldDataType; + + /** PIM value array */ + RPointerArray< CPIMValueBase> iValues; + +}; + +#endif // CPIMFIELD_H +// End of file