/*+
−
* Copyright (c) 2004 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:  Presence attribute model interface & related definitions.+
−
*+
−
*/+
−
+
−
#ifndef __MPENGPRESENCEATTRMODEL2_H+
−
#define __MPENGPRESENCEATTRMODEL2_H+
−
+
−
//  INCLUDES+
−
#include <E32Std.h>+
−
#include <PEngPresenceEngineConsts2.h>+
−
+
−
+
−
+
−
//FORWARD DECLARATIONS+
−
class MPEngAttrModelExtension2;+
−
class MPEngPresenceAdvancedAttrModel2;+
−
class MPEngPresenceAttrTypeProperties2;+
−
+
−
+
−
+
−
// DATA DECLARATION+
−
/**+
−
 * Attribute model data source.+
−
 *+
−
 * Attribute model data source identifies source+
−
 * of the currently handled attribute model data.+
−
 *+
−
 * @since 3.0+
−
 */+
−
enum TPEngAttrDataSource+
−
    {+
−
    /**+
−
     * Presence attribute data is committed to network.+
−
     */+
−
    EPEngAttrNetwork = 1,+
−
+
−
+
−
    /**+
−
     * Presence attribute data is locally edited.+
−
     */+
−
    EPEngAttrLocalEdited,+
−
+
−
    /**+
−
     * Data is local default.+
−
     * Attribute has it attribute type specific default values.+
−
     */+
−
    EPEngAttrLocalDefault+
−
    };+
−
+
−
+
−
+
−
+
−
/**+
−
 * Default group value for simple+
−
 * structured presence attributes.+
−
 *+
−
 * @since 3.0+
−
 */+
−
const TInt KPEngDefaultAttrValueGroup = -1;+
−
+
−
+
−
+
−
+
−
// CLASS DECLARATION+
−
+
−
/**+
−
 * Abstract interface for Presence Attribute models.+
−
 *+
−
 * Presence Attribute present Presence Attribute data.+
−
 * Attribute model interface defines uniform way to+
−
 * access and edit presence attributes.+
−
 *+
−
 * Each concrete attribute type supports just certain,+
−
 * most suitable, data set and get methods.+
−
 *+
−
 * @since 3.0+
−
 */+
−
class MPEngPresenceAttrModel2+
−
    {+
−
    public: //Attribute type details+
−
+
−
        /**+
−
         * Attribute type ID.+
−
         *+
−
         * Returns ID identifying type of handled attribute model.+
−
         * See attribute type documentation for information+
−
         * about available attributes.+
−
         *+
−
         * Attribute type identifies the presence data hold in+
−
         * the handled attribute model. Each concrete attribute+
−
         * type has its own data semantics that has to be known+
−
         * before using the attribute model.+
−
         *+
−
         * Presence Engine known attribute types are listed+
−
         * in PEngWVPresenceAttributes2.h. Currently supported+
−
         * types are:+
−
         *  - KUidPrAttrOnlineStatus+
−
         *  - KUidPrAttrClientInfo+
−
         *  - KUidPrAttrCommCap+
−
         *  - KUidPrAttrUserAvailability+
−
         *  - KUidPrAttrStatusText+
−
         *  - KUidPrAttrStatusContent (former KUidPrAttrMyLogoStatusContent)+
−
         *  - KUidPrAttrMyLogoThumbnail+
−
         *  - KUidPrAttrInfoLink+
−
         *  - KUidPrAttrAlias+
−
         *+
−
         * @since 3.0+
−
         * @return Attribute model type ID.+
−
         */+
−
        virtual TUint32 Type() const = 0;+
−
+
−
+
−
        /**+
−
         * Attribute type properties.+
−
         *+
−
         * Returns abstract interface which can be used to+
−
         * query different attribute type specific+
−
         * properties like attribute type XML name etc.+
−
         *+
−
         * Lifetime of the returned property interface+
−
         * is guaranteed to be valid only as long as+
−
         * the attribute model. Property object+
−
         * ownership is kept on attribute model.+
−
         *+
−
         * @since 3.0+
−
         * @return The attribute type properties.+
−
         */+
−
        virtual const MPEngPresenceAttrTypeProperties2& TypeProperties() const = 0;+
−
+
−
+
−
+
−
        /**+
−
         * Makes a new deep copy from attribute model object.+
−
         *+
−
         * Returns new object ownership to caller.+
−
         * Returned object can be only read.+
−
         * @since 3.0+
−
         */+
−
        virtual MPEngPresenceAttrModel2* CloneLC() const = 0;+
−
+
−
+
−
+
−
+
−
    public: //Attribute instance details+
−
+
−
        /**+
−
         * Gets the attribute owners presence ID.+
−
         *+
−
         * @since 3.0+
−
         * @return Attribute owner presence ID. For user own+
−
         * attributes, method returns empty string.+
−
         * (KPEngUserOwnPresenceId from PEngPresenceEngineConsts2.h)+
−
         */+
−
        virtual const TDesC& PresenceID() const = 0;+
−
+
−
+
−
        /**+
−
         * Attribute current data source.+
−
         *+
−
         * @since 3.0+
−
         * @return Enumeration specifying attribute data source.+
−
         */+
−
        virtual TPEngAttrDataSource DataSource() const = 0;+
−
+
−
+
−
+
−
+
−
    public: //Attribute data getters+
−
+
−
+
−
        /**+
−
         * Attribute qualifier.+
−
         *+
−
         * @since 3.0+
−
         * @return A TBool indicating attribute qualification.+
−
         * ETrue if the attribute qualifier is TRUE.+
−
         * EFalse if the attribute qualifier is FALSE.+
−
         */+
−
        virtual TBool Qualifier() const = 0;+
−
+
−
+
−
+
−
        /**+
−
         * Gets integer or 8/16 bit descriptor value.+
−
         *  - Integer values are usually attribute type+
−
         *    specific enumerations.+
−
         *  - 8 bit descriptor values are attribute type specific+
−
         *    data buffers or similar objects.+
−
         *  - 16 bit descriptor values are usually a screen texts.+
−
         *+
−
         *+
−
         * Common error handling:+
−
         * 1. Attribute type doesn't support given scope (field/group):+
−
         *    - debug build: panic,+
−
         *    - release build: return KErrNotSupported / empty descriptor+
−
         *+
−
         * 2. Attribute type doesn't support getting specified type:+
−
         *    - debug build: panic+
−
         *    - release build: return KErrNotSupported / empty descriptor+
−
         *+
−
         * @since 3.0+
−
         * @param aField The field of the attribute value.+
−
         * @param aGroup The group of individual attribute field.+
−
         * @return The integer or 8/16 bit descriptor data.+
−
         */+
−
        virtual TInt DataInt(+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) const = 0;+
−
+
−
        virtual const TPtrC8 DataDesC8(+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) const = 0;+
−
+
−
        virtual const TPtrC16 DataDesC16(+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) const = 0;+
−
+
−
+
−
+
−
+
−
+
−
+
−
    public: //Attribute data mutators+
−
+
−
+
−
        /**+
−
         * Sets attribute qualifier.+
−
         *+
−
         * Basicly most of time the attribute qualifier should+
−
         * remain set to true.+
−
         *+
−
         * NOTE!! Successful setting the attribute data from+
−
         * client side causes automaticly the qualifier to be set+
−
         * to true.+
−
         *+
−
         * @since 3.0+
−
         * @param aQualifier A TBool indicating attribute qualification.+
−
         * If ETrue, then the attribute qualifier is set to TRUE.+
−
         * If EFalse, then the attribute qualifier is set to FALSE.+
−
         */+
−
        virtual void SetQualifier( TBool aQualifier ) = 0;+
−
+
−
+
−
+
−
        /**+
−
         * Sets integer or 8/16 bit descriptor value.+
−
         *  - Integer values are usually attribute type+
−
         *    specific enumerations.+
−
         *  - 8 bit descriptor values are attribute type specific+
−
         *    data buffers or similar objects.+
−
         *  - 16 bit descriptor values are usually a screen texts.+
−
         *+
−
         * If value set operation succeeds, sets also the+
−
         * attribute qualifier to TRUE.+
−
         *+
−
         * Common error handling:+
−
         * 1. Attribute type doesn't support given scope (field/group):+
−
         *    - debug build: panic+
−
         *    - release build: leave KErrNotSupported+
−
         *+
−
         * 2. Attribute type doesn't support given integer value,+
−
         *    or descriptor value is out of attribute type specific bounds:+
−
         *    - debug build: panic+
−
         *    - release build: leave KErrArgument+
−
         *+
−
         * 3. Attribute type doesn't support setting specified type:+
−
         *    - debug build: panic+
−
         *    - release build: leave KErrNotSupported+
−
         *+
−
         * 4. Concrete attribute might do also other checks and+
−
         *    conversions for the data. If these fail, data set+
−
         *    operation fails and leaves with error code coming from+
−
         *    concrete attribute implementation.+
−
         *+
−
         * @since 3.0+
−
         * @param aData The new integer or 8/16 bit descriptor data.+
−
         * @param aField The field of the attribute value.+
−
         * @param aGroup The group of individual attribute field.+
−
         */+
−
        virtual void SetDataIntL(+
−
            TInt aData,+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) = 0;+
−
+
−
        virtual void SetDataDesC8L(+
−
            const TDesC8& aData,+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) = 0;+
−
+
−
        virtual void SetDataDesC16L(+
−
            const TDesC16& aData,+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) = 0;+
−
+
−
+
−
        /**+
−
         * Sets 8/16 bit descriptor value with asynchronous processing.+
−
         *+
−
         * Sets 8/16 bit descriptor value and performs asynchronous+
−
         * processing for validating or converting the value.+
−
         *+
−
         * If value set operation succeeds, sets also the+
−
         * attribute qualifier to TRUE.+
−
         *+
−
         * If attribute has several asynchronously set data+
−
         * fields, only one set operation is suppoted at time.+
−
         *+
−
         * Common error handling:+
−
         * 1. Attribute type doesn't support given scope (field/group):+
−
         *    - debug build: panic+
−
         *    - release build: leave KErrNotSupported+
−
         *+
−
         * 2. Attribute type doesn't support setting specified data type+
−
         *    asynchronously:+
−
         *    - debug build: panic+
−
         *    - release build: leave KErrNotSupported+
−
         *+
−
         * 3. Asynchronous processing starting fails:+
−
         *  - leaves with error codes coming from concrete implementation.+
−
         *+
−
         *+
−
         * @since 3.0+
−
         * @param aData The 8/16 bit descriptor data.+
−
         * @param aRequestStatus Asynchronous completion code.+
−
         * The attribute model sets the passed request status to+
−
         * KRequestPending state if asynchronous processing is started.+
−
         * When asynchronous processing completes, successfully or otherwise,+
−
         * the end status is returned in aRequestStatus.+
−
         * - KErrNone if processing was successful. In this case+
−
         *   attribute qualifier is set to ETrue.+
−
         * - Else an attribute type specific error code or+
−
         *   one of the system-wide error codes.+
−
         *+
−
         * @param aField The field of the attribute value.+
−
         * @param aGroup The group of individual attribute field.+
−
         */+
−
        virtual void SetDataDesC8AsyncL(+
−
            const TDesC8& aData,+
−
            TRequestStatus& aRequestStatus,+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) = 0;+
−
+
−
        virtual void SetDataDesC16AsyncL(+
−
            const TDesC16& aData,+
−
            TRequestStatus& aRequestStatus,+
−
            TInt aField,+
−
            TInt aGroup = KPEngDefaultAttrValueGroup ) = 0;+
−
+
−
+
−
        /**+
−
         * Cancels previously issued asynchronous set processing.+
−
         *+
−
         * Attribute value state after cancelling depends from+
−
         * concrete attribute type.+
−
         *+
−
         * @since 3.0+
−
         */+
−
        virtual void CancelSetDataAsync() = 0;+
−
+
−
+
−
+
−
+
−
+
−
    private: //Extensions interfaces+
−
+
−
+
−
        /**+
−
         * Generic attribute model extension interface.+
−
         *+
−
         * @since 3.0+
−
         * @return Attribute model extension.+
−
         */+
−
        virtual const MPEngAttrModelExtension2* Extension() const = 0;+
−
        virtual MPEngAttrModelExtension2* Extension() = 0;+
−
+
−
+
−
+
−
        /**+
−
         * Attribute model type specific extension.+
−
         *+
−
         * @since 3.0+
−
         * @return Attribute type specific extension.+
−
         */+
−
        virtual TAny* TypeExtension( TUint32 aType ) = 0;+
−
+
−
+
−
+
−
    public: //Presence Engine internal interface access+
−
+
−
        /**+
−
         * Presence Engine internal attribute model interface.+
−
         *+
−
         * @since 3.0+
−
         * @return Attribute model internal interface.+
−
         */+
−
        virtual const MPEngPresenceAdvancedAttrModel2* Advanced() const = 0;+
−
        virtual MPEngPresenceAdvancedAttrModel2* Advanced() = 0;+
−
+
−
+
−
+
−
    public: //Cleanup support & destructor+
−
+
−
        /**+
−
         * Support for attribute model cleanup.+
−
         *+
−
         * When this method is called, concrete+
−
         * attribute object is deleted and all+
−
         * it runtime resources are freed.+
−
         * ==> Attribute models can be pushed on the+
−
         * CleanupStack using CleanupClosePushL().+
−
         *+
−
         * @since 3.0+
−
         */+
−
        virtual void Close() = 0;+
−
+
−
+
−
        /**+
−
         * Inline virtual destructor. Concrete+
−
         * attribute objects can be deleted through+
−
         * this interface.+
−
         *+
−
         * Deleting cancels possibly active+
−
         * asynchronous processing operations.+
−
         *+
−
         * @since 3.0+
−
         */+
−
        virtual ~MPEngPresenceAttrModel2() {};+
−
+
−
    };+
−
+
−
+
−
#endif      // __MPENGPRESENCEATTRMODEL2_H+
−
+
−
+
−
+
−
//  End of File+
−
+
−
+
−