diff -r 000000000000 -r e686773b3f54 contacts_plat/presence_cache_api/inc/mpresencebuddyinfo2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/contacts_plat/presence_cache_api/inc/mpresencebuddyinfo2.h Tue Feb 02 10:12:17 2010 +0200 @@ -0,0 +1,340 @@ +/* +* 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: Interface for presence buddy presence info. +* +*/ + +#ifndef MPRESENCEBUDDYINFO2_H +#define MPRESENCEBUDDYINFO2_H + +#include +#include + +#include + +class RWriteStream; +class RReadStream; + + /** + * Common field names. + * If you make your own extension it is recommended to use "x-" prefix in your fields, + * e.g. "x-myapp-location". + */ + namespace NPresenceCacheFieldName + { + + /** + * Field type for "status message" field. + * + * Status message field contains user written + * free text, describing for example his/hers current + * presence status. Status message is in unicode format. + */ + _LIT( KStatusMessage, "statustext"); + + /** + * Field type for "avatar" field. + * + * Avatar field contains user selected image. Image may be + * an avatar describing the user or it may be image showing + * user current presence status. + * + * Image is in JPEG or similar format, for what there exists + * image codes in the platform. Field contains image binary + * content and MIME string describing the content format. + */ + _LIT( KAvatar, "avatar"); + + + /** + * Field type for "availability-text" field. + * + * Availability text field describes presentity's communication + * availability as text. This is useful in case of brande + * presence availability, since any text value is possible. + * + * Field storage format: MPresenceInfoFieldValueText + */ + _LIT( KAvailability, "availabilitytext"); + + /** + * Field type for "serviceiconbrandid-text" field. + * + * Service icon brand ID text field identifies the service brand which + * the current presence information is from. Brand information can + * be used with BrandingServer to fetch branded content to UI. + * + * Field storage format: 8bit descriptor + */ + _LIT( KServiceIconBrand, "ServiceBrandingID" ); + + /** + * Field type for "serviceiconentryid-text" field. + * + * Service icon entry ID text field identifies the icon which represents + * the current presence service. Icon id can be used with branding + * information to fetch the actual image from BrandingServer. + * + * Field storage format: 8bit descriptor + */ + _LIT( KServiceIconId, "ServiceIconEntryID" ); + + /** + * Field type for "timestamp" field. + * + * TimeStamp field represents the time when the presence information + * was last updated. Client can show the TimeStamp on the UI or omit + * old presence information completely. + * + * Field storage format: TPckg + * + * Write example: + * TTime time; + * time.HomeTime(); + * TPckg timePck( time ); + * aBuddyInfo.SetAnyFieldL( KTimeStamp, timePck ); + * + * Read example: + * TTime time; + * TPckg timePck( time ); + * timePck.Copy( aBuddyInfo.GetAnyField( KTimeStamp ) ); + */ + _LIT( KTimeStamp, "TimeStamp" ); + + /** + * Field type for "expiry" field. + * + * Expiry field represents the time (microseconds) how long buddy + * information is valid with out new buddy info write events. + * See @MPresenceCacheWriter2 + * If Buddy information is not updated in expiry time then buddy + * information is removed automatilly from presence cache. + * + * Field storage format: TPckg + * + * Write example: + * TInt64 expiry([EXPIRY_TIME]); + * TPckg expiryPck( expiry ); + * aBuddyInfo.SetAnyFieldL( + * NPresenceCacheFieldName::KExpiry, expiryPck ); + * + * Read example: + * TInt64 expiry; + * TPckg expiryPck( expiry ); + * expiryPck.Copy( aBuddyInfo.GetAnyField( + * NPresenceCacheFieldName::KExpiry ) ); + */ + _LIT( KExpiry, "expiry" ); + + } + +/** + * Interface buddy presence info. + * + * @since S60 v5.1 + */ + + +class MPresenceBuddyInfo2 +{ +public: + + /** + * Common enumerated availability values for "availability" + * presence information field. + * + * @since S60 v5.1 + */ + enum TAvailabilityValues + { + /** + * Presentity status is unknown. + */ + EUnknownAvailability = 0, + + /** + * Presentity is not available for communication. + */ + ENotAvailable = 1, + + /** + * Presentity is currently busy. + * Presentity may or may not be available + * for for communication. + */ + EBusy = 2, + + /** + * Presentity is available for communication. + */ + EAvailable = 3 + }; + + + /** + * Factory method to instantiate MPresenceBuddyInfo2 + * + * @return The new MPresenceFeeder object. Object + * ownership is returned to caller. + */ + IMPORT_C static MPresenceBuddyInfo2* NewL( ); + + /** + * Factory method to instantiate MPresenceBuddyInfo2 + * + * @return The new MPresenceFeeder object. Object + * ownership is returned to caller. + */ + IMPORT_C static MPresenceBuddyInfo2* NewLC( ); + + + + /** + * Public destructor. + * Objects can be deleted through this interface. + */ + virtual ~MPresenceBuddyInfo2() {} + +public: + + /** + * Sets buddy's identity + * + * @param aBuddyId buddy id + */ + virtual void SetIdentityL( const TDesC& aBuddyId ) = 0; + + /** + * Gets buddy's identity + * + * @return identity + */ + virtual TPtrC BuddyId( ) const = 0; + + /** + * Sets buddy's availability + * + * @param aAvailability avalability value + * @param aAvailabilityText avalability text, same as KAvailability field + */ + virtual void SetAvailabilityL( + TAvailabilityValues aAvailability, + const TDesC& aAvailabilityText ) = 0; + + /** + * Gets buddy's availability + * + * @return availability + */ + virtual TAvailabilityValues Availability( ) = 0; + + /** + * Gets buddy's availability text + * + * @return availability text + */ + virtual TPtrC AvailabilityText( ) = 0; + + + /** + * Sets buddy's avatar + * + * @param aAvatar avatar, same as KAvatar field + */ + virtual void SetAvatarL( const TDesC8& aAvatar ) = 0; + + /** + * Gets buddy's avatar + * + * @return avatar + */ + virtual TPtrC8 Avatar( ) = 0; + + /** + * Sets buddy's status text + * + * @param aStatusMessage status text, same as KStatusMessage field + */ + virtual void SetStatusMessageL( + const TDesC& aStatusMessage ) = 0; + + /** + * Gets buddy's status text. + * + * @return status text, same as KStatusMessage field + */ + virtual TPtrC StatusMessage( ) = 0; + + /** + * Sets any key value parameter for the buddy + * + * @param aKey field name + * @param aValue field value + */ + virtual void SetAnyFieldL( + const TDesC16& aKey, + const TDesC8& aValue ) = 0; + + /** + * Gets any key value parameter for the buddy + * + * @param aKey field name + * @return field value, zero length if not found. + */ + virtual TPtrC8 GetAnyField( + const TDesC16& aKey ) = 0; + + /** + * Gets all the keys that are in use + * + * @param aKeys array where the keys are written to. + */ + virtual void GetFieldKeysL( + CDesCArrayFlat& aKeys ) = 0; + + /** + * Removes the field + * @param aKey field name + */ + virtual void RemoveField(const TDesC& aKey ) = 0; + + + /** + * Return true if identity is same with other instance. + * + * @param aOtherInstance other instance of this object. + * @return ETrue if same. + */ + virtual TBool EqualsIdentity( + const MPresenceBuddyInfo2& aOtherInstance ) const = 0; + + /** + * Externalize + * @param aStream write stream + */ + virtual void ExternalizeL( RWriteStream& aStream ) const = 0; + + + /** + * Internalize + * @param aStream read stream + */ + virtual void InternalizeL( RReadStream& aStream ) = 0; + + }; + +#endif // MPRESENCEBUDDYINFO2_H + + +