--- /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 <e32std.h>
+#include <badesca.h>
+
+#include <s32strm.h>
+
+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<TTime>
+ *
+ * Write example:
+ * TTime time;
+ * time.HomeTime();
+ * TPckg<TTime> timePck( time );
+ * aBuddyInfo.SetAnyFieldL( KTimeStamp, timePck );
+ *
+ * Read example:
+ * TTime time;
+ * TPckg<TTime> 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<TInt64>
+ *
+ * Write example:
+ * TInt64 expiry([EXPIRY_TIME]);
+ * TPckg<TInt64> expiryPck( expiry );
+ * aBuddyInfo.SetAnyFieldL(
+ * NPresenceCacheFieldName::KExpiry, expiryPck );
+ *
+ * Read example:
+ * TInt64 expiry;
+ * TPckg<TInt64> 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
+
+
+