/*

* 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