diff -r 000000000000 -r 094583676ce7 PECengine/IncApi/CPEngNWSessionSlotManager2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/PECengine/IncApi/CPEngNWSessionSlotManager2.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,246 @@ +/* +* 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: API to manage NWSessionSlots. +* +*/ + +#ifndef __CPENGNWSESSIONSLOTMANAGER2_H +#define __CPENGNWSESSIONSLOTMANAGER2_H + +// INCLUDES +#include +#include + + + + +// FORWARD DECLARATIONS +class CPEngNWSessionSlotManager2Imp; +class CPEngNWSessionSlotID2; + + +// CLASS DECLARATION +/** + * CPEngNWSessionSlotManager2 to manage NWSessionSlots. + * + * Services: + * - Create, remove and list NWSessionSlots + * - Query certain NWSessionSlot's state + * + * @lib PEngManager2.lib + * @since 3.0 + */ +class CPEngNWSessionSlotManager2 : public CBase + { + + //----------------------------------------------------------------------- + public: /* Construction */ + + /** + * Instantiates NWSessionSlotManager object. + * + * Instantiates NWSessionSlotManager object and connects it to + * PresenceEngine subsystem. If needed PresenceEngine servers + * aren't yet running, starts those before returning from method. + * + * @param aPriority The priority for Presence Engine client side active + * objects. These active objects are used when asynchronously delivering + * events to observers or maintaining Presence Cache state. + * + * @return New CPEngNWSessionSlotManager2 instance. + */ + IMPORT_C static CPEngNWSessionSlotManager2* NewL( + TInt aPriority = CActive::EPriorityStandard ); + + IMPORT_C static CPEngNWSessionSlotManager2* NewLC( + TInt aPriority = CActive::EPriorityStandard ); + + + /** + * Destructor. + * Virtual by CBase. + */ + ~CPEngNWSessionSlotManager2(); + + + private: + + CPEngNWSessionSlotManager2(); + + + + //----------------------------------------------------------------------- + public: /* NWSessionSlot management */ + + + /** + * Creates a new NWSessionSlot to Presence Engine. + * + * Creates a new NWSessionSlot to Presence Engine. + * After creation NWSessionSlot can be used: + * - it can be connected to network server + * - its data can be edited + * - its data can be published and synchronized with network server + * - data can be fetched from network server to local storage + * + * NWSessionSlots are identified with NWSessionSlotID. + * One NWSessionSlot is tightly coupled to certain network service, + * and in practice NWSessionSlot can be connected only to service + * defined in its NWSessionSlotID. + * + * When a new NWSessionSlot is created, it is + * - in offline state + * - it has no session SAP settings defined + * - it has no contact lists defined nor any contact list data + * - it has no attribute lists defined + * - user own attributes are in their default state + * - and no subscribed presence attributes + * + * @param aNWSessionSlotID The session slot ID to use to + * identify the new NWSessionSlot. + * + * @return Result: + * - KErrNone if creation succeeds. + * - KErrAlreadyExist if NWSessionSlot with given ID exists already + * - KErrArgument if NWSessionSlotID is malformed + * - Or one of the system wide error codes + */ + IMPORT_C TInt CreateNWSessionSlot( + const CPEngNWSessionSlotID2& aNWSessionSlotID ); + + + + /** + * Removes existing NWSessionSlot from Presence Engine. + * + * Removes existing NWSessionSlot from Presence Engine. + * Remove fails if there is somewhere in system a open handle + * to NWSessionSlot. + * ==> - Client responsible for NW Session slot creation and + * removal must be prepared to do the garbage collect for + * NWSessionSlot's at suitable point. This could be done + * for example at boot up, when there isn't yet + * clients connected to NWSessionSlots. + * - All Presence Engine API objects which construction + * take NWSessionSlotID parameter (e.g. CPEngAttributeStore + * and CPEngAttributePublisher) have in practise a + * open handle to NWSessionSlot. Also some presence model + * objects (e.g MPEngContactList2 and MPEngPresenceAttrModel2) + * are having such handles also. + * + * @param aNWSessionSlotID The NWSessionSlot to remove. + * + * @return Result: + * - KErrNone if remove succeeds. + * - KErrNotFound if NWSessionSlot with given ID isn't found + * - KErrArgument if given NWSessionSlotID malformed + * - KErrInUse if NWSessionSlot is in use + * - Or one of the system wide error codes + */ + IMPORT_C TInt RemoveNWSessionSlot( + const CPEngNWSessionSlotID2& aNWSessionSlotID ); + + + + + + //----------------------------------------------------------------------- + public: /* NWSessionSlot information access */ + + /** + * Gets a list of all existing NWSessionSlots. + * + * @param aNWSessionSlotIDs On the return contains ID's of all existing + * NWSessionSlots. Appends the ID's in the end of array. + * Possibly existing objects in the array are not touched. + * Ownership of created objects is returned to caller. In case + * of error, returns ID's retrieved before the error. + * + * @return KErrNone or one of the system wide error codes. + */ + IMPORT_C TInt GetNWSessionSlots( + RPointerArray< CPEngNWSessionSlotID2 >& aNWSessionSlotIDs ) const; + + + /** + * Gets a list of existing NWSessionSlots. + * + * Overloaded version for getting NWSessionSlots which + * NWSessionSlotID matches the given match pattern and + * which state matches given state. + * + * @param aNWSessionSlotIDs On the return contains ID's of matching + * NWSessionSlots. Appends the ID's in the end of array. + * Possibly existing objects in the array are not touched. + * Ownership of created objects is returned to caller. In case + * of error, returns ID's retrieved before the error. + * + * @param aMatchPattern The match pattern to use + * to filter the returned NWSessionSlotIDs. Only those + * slots which ID match given match pattern, are returned. + * + * @param aMatchState The state match pattern to use to filter + * the returned NWSessionSlotIDs. Only those slots which + * state is same as given state are returned. + * + * @return KErrNone or one of the system wide error codes. + */ + IMPORT_C TInt GetNWSessionSlots( + RPointerArray< CPEngNWSessionSlotID2 >& aNWSessionSlotIDs, + const CPEngNWSessionSlotID2& aMatchPattern, + TPEngNWSessionSlotState aMatchState ) const; + + + + /** + * Tests does the given NWSessionSlot exist. + * + * Tests does there exist a given NWSessionSlot. + * NWSessionSlotId must be fully defined. + * + * @param aNWSessionSlotID NWSessionSlotID to check. + * @return Result: + * - KErrNone if matching NWSessionSlot exist. + * - KErrNotFound if matching NWSessionSlot not found. + * - KErrArgument if given NWSessionSlotID malformed + * - Else one of system wide error codes. + */ + IMPORT_C TInt ExistsNWSessionSlot( + const CPEngNWSessionSlotID2& aNWSessionSlotID ) const; + + + + //----------------------------------------------------------------------- + private: /* Data */ + + + //OWN: Implementation + CPEngNWSessionSlotManager2Imp* iImp; + + + }; + + +#endif //__CPENGNWSESSIONSLOTMANAGER2_H + + +//End of file + + + + + + + +