/*
* 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