/*

* 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