diff -r 6ca72c0fe49a -r a941bc465d9f inc/CPEngAttributeTransaction2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/CPEngAttributeTransaction2.h Wed Sep 01 12:31:13 2010 +0100 @@ -0,0 +1,311 @@ +/* +* 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 +#include + + +// 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& 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& aTypes, + MPEngAttributeTransactionObserver2& aObserver, + TInt aOptions = 0 ); + + IMPORT_C TInt FetchAttributesToCache( + const MDesCArray& aPresenceIDs, + const TArray& 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& 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 + + + + + + +