/*
* 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 <E32Base.h>
#include <PEngPresenceEngineConsts2.h>
// 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