/*
* 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 transactions.
*
*/
#ifndef __CPENGATTRIBUTETRANSACTION2_H
#define __CPENGATTRIBUTETRANSACTION2_H
// INCLUDES
#include <E32Base.h>
#include <BamDescA.h>
// FORWARD DECLARATIONS
class CPEngAttributeTransaction2Imp;
class CPEngNWSessionSlotID2;
class MPEngAttributeTransactionObserver2;
class MPEngPresenceAttrModel2;
// CLASS DECLARATION
/**
* Transaction API for presence attributes.
*
* With this API clients can:
*
* 1. Publish user own presence attributes to network.
* 2. Fetch presence attributes from network.
*
* Attribute publish and attribute fetch are asynchronous
* network operations, and their end results are signalled
* to given operation observer.
*
* @lib PEngManager2.lib
* @since 3.0
*/
class CPEngAttributeTransaction2 : public CBase
{
//-----------------------------------------------------------------------
public: /* Construction */
/**
* Instantiates CPEngAttributeTransaction2 object.
*
* Instantiates CPEngAttributeTransaction2 object and connects
* it to identified Presence Engine NWSessionSlot. NWSessionSlot
* must be a valid, existing slot.
*
* Errors:
* - Requested NWSessionSlot not found: KErrNotFound
* - Given NWSessionSlotID malformed: KErrArgument
*
* @param aNWSessionSlotID The session slot ID to identify the
* session slot.
* @param aPriority The priority for CPEngAttributeTransaction2
* client side active objects. These active objects are used when
* asynchronously delivering events to observers.
*
* @return New CPEngAttributeTransaction2 instance.
*/
IMPORT_C static CPEngAttributeTransaction2* NewL(
const CPEngNWSessionSlotID2& aNWSessionSlotID,
TInt aPriority = CActive::EPriorityStandard );
IMPORT_C static CPEngAttributeTransaction2* NewLC(
const CPEngNWSessionSlotID2& aNWSessionSlotID,
TInt aPriority = CActive::EPriorityStandard );
/**
* Destructor.
* Virtual by CBase.
*/
~CPEngAttributeTransaction2();
private:
CPEngAttributeTransaction2();
//-----------------------------------------------------------------------
public: /* User own attribute publish */
/**
* Tests is the publish already active.
*
* @since 3.0
* @return ETrue if operation is active. Else EFalse.
*/
IMPORT_C TBool IsPublishOwnAttributesActive() const;
/**
* Publishes the user own attribute to the network server.
*
* Published attribute is kept locked untill the publish
* operation completes (either succesfully or with failure).
*
* There can be just one active publish operation at a time
* per one CPEngAttributeTransaction2 instance. However,
* there can be simultaneously several publish operations
* going on within one NWSessionSlot with distinct
* CPEngAttributeTransaction2 objects and distinct attribute sets.
*
* Takes ownership to passed model(s). If method returns error,
* the model(s) ownership remains on the client. In success sets
* the given model pointer to NULL or resets the parameter model
* array.
*
* Passed models must be loaded from same NWSessionSlot as
* CPEngAttributeTransaction2 is connected and attribute
* models must be locked for edit/publish.
*
* @since 3.0
* @param aModel The attribute model to publish.
* @param aObserver The observer to notify from attribute
* publish events.
*
* @return Result from initiating attribute publish:
* - KErrNone if attribute publish succesfully initiated.
* - KErrInUse if attribute publish already on going from object.
* - KErrArgument if attributes either loaded from another
* NWSessionSlot or they are not locked for edit.
* - Else one of system wide error codes.
*/
IMPORT_C TInt PublishAndUnLockOwnAttribute(
MPEngPresenceAttrModel2*& aModel,
MPEngAttributeTransactionObserver2& aObserver );
IMPORT_C TInt PublishAndUnLockOwnAttributes(
RPointerArray<MPEngPresenceAttrModel2>& aModels,
MPEngAttributeTransactionObserver2& aObserver );
/**
* Cancels the user attribute publish.
*
* @since 3.0
*/
IMPORT_C void CancelPublishOwnAttributes();
//-----------------------------------------------------------------------
public: /* Presence attribute fetch from network */
/**
* Tests is the fetch already active.
*
* @since 3.0
* @return ETrue if operation is active. Else EFalse.
*/
IMPORT_C TBool IsFetchAttributesActive() const;
/**
* Fetches presence attributes from network server.
*
* Fetches presence attributes from the network
* and stores fetched attributes to presence cache.
* (Fetched presence attributes can be retrieved e.g. with
* CPEngAttributeStore2::GetCachedAttributeL().)
*
* There can be just one active fetch operation at a time
* per one CPEngAttributePublisher instance. However, within
* one NWSessionSlot there can be several active fetch
* operations going on.
*
* @since 3.0
* @param aPresenceID The user to fetch.
* @param aType The attribute type. Presence Engine known
* attribute types are listed in PEngWVPresenceAttributes2.h.
* @param aObserver The observer to notify from attribute fetch events.
* @param aOptions Reserved for future fetch options.
*
* @return Result from initiating attribute fetch:
* - KErrNone if attribute fetch succesfully initiated.
* - KErrInUse if attribute fetch already on going from object.
* - KErrNotSupported if requestSed attribute type isn't supported.
* - Else one of system wide error codes.
*/
IMPORT_C TInt FetchAttributesToCache(
const TDesC& aPresenceID,
const TArray<TUint32>& aTypes,
MPEngAttributeTransactionObserver2& aObserver,
TInt aOptions = 0 );
IMPORT_C TInt FetchAttributesToCache(
const MDesCArray& aPresenceIDs,
const TArray<TUint32>& aTypes,
MPEngAttributeTransactionObserver2& aObserver,
TInt aOptions = 0 );
/**
* Fetches presence attributes from network server.
*
* Fetches presence attributes from the network
* and returns them to client as local objects.
* Client can ask the fetched presence attributes
* after succesfull fetch from
* CPEngAttributeTransaction2::GetFetchedAttributes().)
*
* There can be just one active fetch operation at a time
* per one CPEngAttributePublisher instance. However, within
* one NWSessionSlot there can be several active fetch
* operations going on.
*
* @since 3.0
* @param aPresenceID The user to fetch.
* @param aType The attribute type. Presence Engine known
* attribute types are listed in PEngWVPresenceAttributes2.h.
* @param aObserver The observer to notify from attribute fetch events.
* @return Result from initiating attribute fetch:
* - KErrNone if attribute fetch succesfully initiated.
* - KErrInUse if attribute fetch already on going from object.
* - KErrNotSupported if requestSed attribute type isn't supported.
* - Else one of system wide error codes.
*/
IMPORT_C TInt FetchAttributesToObjects(
const TDesC& aPresenceID,
const TArray<TUint32>& aTypes,
MPEngAttributeTransactionObserver2& aObserver );
/**
* Cancels the presence attribute fetch.
*
* @since 3.0
*/
IMPORT_C void CancelFetchAttributes();
//-----------------------------------------------------------------------
public: /* Object get for observer callbacks */
/**
* Gets the fetched attribute objects produced by the last
* FetchAttributesToObjects(). Ownership of attribute models is
* returned to caller. Returned models can be only read.
*
* Fetched attributes can be asked only during the observer callback:
* MPEngAttributeTransactionObserver2::HandleAttributeTransactionCompleteL().
* After retrieving the models, client owns the attribute objects and
* can freely control their lifetime.
*
* @since 3.0
* @param aModel Returns retrieved attribute model(s).
* Retrieved attribute models are appended to the end of array.
* If array has existing attribute objects, those are not touched.
* If get fails with resource error, so far succesfully
* moved attributes are returned.
*
* @return Status code from attribute getting:
* - KErrNone if get succeeds.
* - KErrNotReady if no fetch results available
* - Else one of system wide error codes.
*/
IMPORT_C TInt GetFetchedAttributes(
RPointerArray< MPEngPresenceAttrModel2 >& aModels );
//-----------------------------------------------------------------------
private: /* Data */
//OWN: Implementation
CPEngAttributeTransaction2Imp* iImp;
};
#endif // __CPENGATTRIBUTETRANSACTION2_H
//End of file