1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  API to manage NWSessionSlots.

    15 *

    16 */

    17 

    18 #ifndef __CPENGNWSESSIONSLOTMANAGER2_H

    19 #define __CPENGNWSESSIONSLOTMANAGER2_H

    20 

    21 //  INCLUDES

    22 #include <E32Base.h>

    23 #include <PEngPresenceEngineConsts2.h>

    24 

    25 

    26 

    27 

    28 // FORWARD DECLARATIONS

    29 class CPEngNWSessionSlotManager2Imp;

    30 class CPEngNWSessionSlotID2;

    31 

    32 

    33 // CLASS DECLARATION

    34 /**

    35  * CPEngNWSessionSlotManager2 to manage NWSessionSlots.

    36  *

    37  * Services:

    38  * - Create, remove and list NWSessionSlots

    39  * - Query certain NWSessionSlot's state

    40  *

    41  * @lib PEngManager2.lib

    42  * @since 3.0

    43  */

    44 class CPEngNWSessionSlotManager2 : public CBase

    45     {

    46 

    47         //-----------------------------------------------------------------------

    48     public: /* Construction */

    49 

    50         /**

    51          * Instantiates NWSessionSlotManager object.

    52          *

    53          * Instantiates NWSessionSlotManager object and connects it to

    54          * PresenceEngine subsystem. If needed PresenceEngine servers

    55          * aren't yet running, starts those before returning from method.

    56          *

    57          * @param aPriority The priority for Presence Engine client side active

    58          * objects. These active objects are used when asynchronously delivering

    59          * events to observers or maintaining Presence Cache state.

    60          *

    61          * @return New CPEngNWSessionSlotManager2 instance.

    62          */

    63         IMPORT_C static CPEngNWSessionSlotManager2* NewL(

    64             TInt aPriority = CActive::EPriorityStandard );

    65 

    66         IMPORT_C static CPEngNWSessionSlotManager2* NewLC(

    67             TInt aPriority = CActive::EPriorityStandard );

    68 

    69 

    70         /**

    71          * Destructor.

    72          * Virtual by CBase.

    73          */

    74         ~CPEngNWSessionSlotManager2();

    75 

    76 

    77     private:

    78 

    79         CPEngNWSessionSlotManager2();

    80 

    81 

    82 

    83         //-----------------------------------------------------------------------

    84     public: /* NWSessionSlot management */

    85 

    86 

    87         /**

    88          * Creates a new NWSessionSlot to Presence Engine.

    89          *

    90          * Creates a new NWSessionSlot to Presence Engine.

    91          * After creation NWSessionSlot can be used:

    92          * - it can be connected to network server

    93          * - its data can be edited

    94          * - its data can be published and synchronized with network server

    95          * - data can be fetched from network server to local storage

    96          *

    97          * NWSessionSlots are identified with NWSessionSlotID.

    98          * One NWSessionSlot is tightly coupled to certain network service,

    99          * and in practice NWSessionSlot can be connected only to service

   100          * defined in its NWSessionSlotID.

   101          *

   102          * When a new NWSessionSlot is created, it is

   103          *  - in offline state

   104          *  - it has no session SAP settings defined

   105          *  - it has no contact lists defined nor any contact list data

   106          *  - it has no attribute lists defined

   107          *  - user own attributes are in their default state

   108          *  - and no subscribed presence attributes

   109          *

   110          * @param aNWSessionSlotID The session slot ID to use to

   111          * identify the new NWSessionSlot.

   112          *

   113          * @return Result:

   114          *  - KErrNone if creation succeeds.

   115          *  - KErrAlreadyExist if NWSessionSlot with given ID exists already

   116          *  - KErrArgument if NWSessionSlotID is malformed

   117          *  - Or one of the system wide error codes

   118          */

   119         IMPORT_C TInt CreateNWSessionSlot(

   120             const CPEngNWSessionSlotID2& aNWSessionSlotID );

   121 

   122 

   123 

   124         /**

   125          * Removes existing NWSessionSlot from Presence Engine.

   126          *

   127          * Removes existing NWSessionSlot from Presence Engine.

   128          * Remove fails if there is somewhere in system a open handle

   129          * to NWSessionSlot.

   130          * ==> - Client responsible for NW Session slot creation and

   131          *       removal must be prepared to do the garbage collect for

   132          *       NWSessionSlot's at suitable point. This could be done

   133          *       for example at boot up, when there isn't yet

   134          *       clients connected to NWSessionSlots.

   135          *     - All Presence Engine API objects which construction

   136          *       take NWSessionSlotID parameter (e.g. CPEngAttributeStore

   137          *       and CPEngAttributePublisher) have in practise a

   138          *       open handle to NWSessionSlot. Also some presence model

   139          *       objects (e.g MPEngContactList2 and MPEngPresenceAttrModel2)

   140          *       are having such handles also.

   141          *

   142          * @param aNWSessionSlotID The NWSessionSlot to remove.

   143          *

   144          * @return Result:

   145          *  - KErrNone if remove succeeds.

   146          *  - KErrNotFound if NWSessionSlot with given ID isn't found

   147          *  - KErrArgument if given NWSessionSlotID malformed

   148          *  - KErrInUse if NWSessionSlot is in use

   149          *  - Or one of the system wide error codes

   150          */

   151         IMPORT_C TInt RemoveNWSessionSlot(

   152             const CPEngNWSessionSlotID2& aNWSessionSlotID );

   153 

   154 

   155 

   156 

   157 

   158         //-----------------------------------------------------------------------

   159     public: /* NWSessionSlot information access */

   160 

   161         /**

   162          * Gets a list of all existing NWSessionSlots.

   163          *

   164          * @param aNWSessionSlotIDs On the return contains ID's of all existing

   165          *        NWSessionSlots. Appends the ID's in the end of array.

   166          *        Possibly existing objects in the array are not touched.

   167          *        Ownership of created objects is returned to caller. In case

   168          *        of error, returns ID's retrieved before the error.

   169          *

   170          * @return KErrNone or one of the system wide error codes.

   171          */

   172         IMPORT_C TInt GetNWSessionSlots(

   173             RPointerArray< CPEngNWSessionSlotID2 >& aNWSessionSlotIDs ) const;

   174 

   175 

   176         /**

   177          * Gets a list of existing NWSessionSlots.

   178          *

   179          * Overloaded version for getting NWSessionSlots which

   180          * NWSessionSlotID matches the given match pattern and

   181          * which state matches given state.

   182          *

   183          * @param aNWSessionSlotIDs On the return contains ID's of matching

   184          *        NWSessionSlots. Appends the ID's in the end of array.

   185          *        Possibly existing objects in the array are not touched.

   186          *        Ownership of created objects is returned to caller. In case

   187          *        of error, returns ID's retrieved before the error.

   188          *

   189          * @param aMatchPattern The match pattern to use

   190          *        to filter the returned NWSessionSlotIDs. Only those

   191          *        slots which ID match given match pattern, are returned.

   192          *

   193          * @param aMatchState The state match pattern to use to filter

   194          *        the returned NWSessionSlotIDs. Only those slots which

   195          *        state is same as given state are returned.

   196          *

   197          * @return KErrNone or one of the system wide error codes.

   198          */

   199         IMPORT_C TInt GetNWSessionSlots(

   200             RPointerArray< CPEngNWSessionSlotID2 >& aNWSessionSlotIDs,

   201             const CPEngNWSessionSlotID2& aMatchPattern,

   202             TPEngNWSessionSlotState aMatchState ) const;

   203 

   204 

   205 

   206         /**

   207          * Tests does the given NWSessionSlot exist.

   208          *

   209          * Tests does there exist a given NWSessionSlot.

   210          * NWSessionSlotId must be fully defined.

   211          *

   212          * @param aNWSessionSlotID NWSessionSlotID to check.

   213          * @return Result:

   214          *  - KErrNone if matching NWSessionSlot exist.

   215          *  - KErrNotFound if matching NWSessionSlot not found.

   216          *  - KErrArgument if given NWSessionSlotID malformed

   217          *  - Else one of system wide error codes.

   218          */

   219         IMPORT_C TInt ExistsNWSessionSlot(

   220             const CPEngNWSessionSlotID2& aNWSessionSlotID ) const;

   221 

   222 

   223 

   224         //-----------------------------------------------------------------------

   225     private: /* Data */

   226 

   227 

   228         //OWN: Implementation

   229         CPEngNWSessionSlotManager2Imp*     iImp;

   230 

   231 

   232     };

   233 

   234 

   235 #endif //__CPENGNWSESSIONSLOTMANAGER2_H

   236 

   237 

   238 //End of file

   239 

   240 

   241 

   242 

   243 

   244 

   245 

   246