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:  Handle to NWSessionSlot.

    15 *

    16 */

    17 

    18 #ifndef __CPENGNWSESSIONSLOT2_H

    19 #define __CPENGNWSESSIONSLOT2_H

    20 

    21 //  INCLUDES

    22 #include <E32Base.h>

    23 #include <BaDesCa.h>

    24 #include <PEngPresenceEngineConsts2.h>

    25 

    26 

    27 

    28 

    29 //FORWARD DECLARATIONS

    30 class MPEngNWSessionOperationObserver2;

    31 class CPEngNWSessionSlot2Imp;

    32 class CPEngNWSessionSlotID2;

    33 class CWVSAPSettings;

    34 class CIMPSSAPSettings;

    35 

    36 

    37 

    38 

    39 

    40 /**

    41  * NWSessionSlot option level.

    42  * Presence transport query.

    43  * @since 3.0

    44  */

    45 const TUint KPEngNWSessionSlotTransportQuery   = 0x2000;

    46 

    47 

    48 

    49 

    50 // CLASS DECLARATION

    51 

    52 /**

    53  * Handle to NWSessionSlot.

    54  *

    55  * NWSessionSlot ties together:

    56  * 1. Network presence session

    57  *    - network presence service is identified by user id

    58  *      and service address

    59  *    - NWSessionSlot holds also other SAP settings needed

    60  *      to connect to network service (IAP ID, user password, etc)

    61  *

    62  * 2. Network session presence data

    63  *    - NWSessionSlot is context for certain network

    64  *      session's presence data

    65  *    - Presence data consists from

    66  *          - contact list setings

    67  *          - contact list data

    68  *          - attribute list data

    69  *          - subscribed / fetched presence attributes

    70  *          - user own attributes

    71  *

    72  *

    73  * NWSessionSlot has a state and event information

    74  * describing its current state.

    75  *

    76  * @lib PEngManager2.lib

    77  * @since 3.0

    78  */

    79 class CPEngNWSessionSlot2 : public CBase

    80     {

    81 

    82         //-----------------------------------------------------------------------

    83     public: /* Construction */

    84 

    85         /**

    86          * Instantiates NWSessionSlot object.

    87          *

    88          * Instantiates NWSessionSlot handle object and connects it to

    89          * identified Presence Engine side NWSessionSlot. NWSessionSlot

    90          * must be a valid, existing slot.

    91          *

    92          * Errors:

    93          *  - Requested NWSessionSlot not found: KErrNotFound

    94          *  - Given NWSessionSlotID malformed: KErrArgument

    95          *

    96          * @param aNWSessionSlotID The session slot ID to identify the

    97          * session slot.

    98          * @param aPriority The priority for CPEngNWSessionSlot2 client

    99          * side active objects. These active objects are used when

   100          * asynchronously delivering events to observers.

   101          *

   102          * @return New CPEngNWSessionSlot2 instance.

   103          */

   104         IMPORT_C static CPEngNWSessionSlot2* NewL(

   105             const CPEngNWSessionSlotID2& aNwSessionSlotID,

   106             TInt aPriority = CActive::EPriorityStandard );

   107 

   108         IMPORT_C static CPEngNWSessionSlot2* NewLC(

   109             const CPEngNWSessionSlotID2& aNWSessionSlotID,

   110             TInt aPriority = CActive::EPriorityStandard );

   111 

   112 

   113         /**

   114          * Destructor.

   115          * Virtual by CBase.

   116          */

   117         ~CPEngNWSessionSlot2();

   118 

   119 

   120 

   121     private:

   122 

   123         CPEngNWSessionSlot2();

   124 

   125 

   126 

   127 

   128         //-----------------------------------------------------------------------

   129     public: /* NW Session Slot configuration */

   130 

   131 

   132         /**

   133          * Gets the NWSessionSlotID.

   134          *

   135          * @since 3.0

   136          * @param aNWSessionSlotID On the return contains the NWSessionSlotID

   137          * of connected NWSessionSlot.

   138          * @return Result from NWSessionSlotID get. One of a system

   139          * wide error codes.

   140          */

   141         IMPORT_C TInt GetNWSessionSlotID(

   142             CPEngNWSessionSlotID2& aNWSessionSlotID ) const;

   143 

   144 

   145 

   146         /**

   147          * Generic getter to access NWSessionSlot options.

   148          *

   149          * Generic getters to access NWSessionSlot options.

   150          * Used for example to get underlying network session

   151          * capabilities. See PEngWVServices2.h for more info about

   152          * WV network capabilities.

   153          *

   154          * @since 3.0

   155          * @param aOptionName Constant which identifies an option.

   156          * @param aOptionLevel Constant which identifies level of an option.

   157          * @param aOption On the return contains actual option value.

   158          * @return Result from option get. Might be a system

   159          * wide error code or error code specific to option.

   160          */

   161         IMPORT_C TInt GetOption( TUint aOptionName,

   162                                  TUint aOptionLevel,

   163                                  TDes8& aOption );

   164 

   165 

   166 

   167         //-----------------------------------------------------------------------

   168     public: /* Network session start and ownership gaining */

   169 

   170 

   171         /**

   172          * Tests is the NWPresenceSession open already active.

   173          *

   174          * @since 3.0

   175          * @return ETrue NWPresenceSession open is active.

   176          * Else EFalse.

   177          */

   178         IMPORT_C TBool IsOpenNWPresenceSessionActive() const;

   179 

   180 

   181         /**

   182          * Opens application network presence session.

   183          *

   184          * Asynchronously opens network presence session for

   185          * application and connects it to given presence network

   186          * service. Result from open is notified to given observer.

   187          *

   188          * - If underlying network CSP session is already open,

   189          *   joins the NWSessionSlot to existing CSP session if SAP

   190          *   settings match.

   191          * - At successful login the client CPEngNWSessionSlot2 instance

   192          *   becomes a NWPresenceSession ownership handle. If client

   193          *   dies or the handle is deleted, the opened NWPresenceSession

   194          *   is automaticly closed, if there isn't other registered

   195          *   session owners. Client can "store" the ownership to system

   196          *   if it doesn't want the automatic close behaviour.

   197          *   See StoreNWPresenceSessionOwnership().

   198          * - Performs network session capability query. Capabilities

   199          *   can be asked from NWSessionSlot after login.

   200          *

   201          * Possible errors:

   202          *   - KErrAlreadyExist - NWPresenceSession already open

   203          *   - Errors specific for real transport

   204          *   - System wide errors

   205          *

   206          * @since 3.0

   207          * @param aSAP The SAP settings to use for NWPresenceSession

   208          * Server address and user ID must match to NWSessionSlotID.

   209          * Overloaded version for CWVSAPSettings and CIMPSSAPSettings.

   210          *

   211          * @param aObserver The observer to notify from session open results.

   212          *

   213          * @return Result from initiating session open.

   214          *  - KErrNone if session open successfully initiated.

   215          *  - KErrInUse if session open already on going from object.

   216          *  - Else one of system wide error codes.

   217          */

   218         IMPORT_C TInt OpenNWPresenceSession(

   219             const CWVSAPSettings& aSAP,

   220             MPEngNWSessionOperationObserver2& aObserver );

   221 

   222         IMPORT_C TInt OpenNWPresenceSession(

   223             const CIMPSSAPSettings& aSAP,

   224             MPEngNWSessionOperationObserver2& aObserver );

   225 

   226         IMPORT_C void CancelOpenNWPresenceSession();

   227 

   228 

   229 

   230         /**

   231          * Gains the network session ownership to this

   232          * CPEngNWSessionSlot2 handle object.

   233          *

   234          * With this method client can get active NWPresenceSession

   235          * ownership to additional handle object. Can be used

   236          * in cases where several applications want to control

   237          * NWPresenceSession lifetime with their own lifetime.

   238          *

   239          * @since 3.0

   240          * @return Result:

   241          * - KErrNone if ownership gaining successfully done.

   242          * - KErrNotSupported if NWPresenceSession not active.

   243          * - Else one of system wide error codes

   244          */

   245         IMPORT_C TInt OpenNWPresenceSessionOwnership();

   246 

   247 

   248 

   249 

   250         //-----------------------------------------------------------------------

   251     public: /* Network session stop and ownership closing */

   252 

   253 

   254         /**

   255          * Tests is the NWPresenceSession close already active.

   256          *

   257          * @since 3.0

   258          * @return ETrue NWPresenceSession close is active.

   259          * Else EFalse.

   260          */

   261         IMPORT_C TBool IsCloseNWPresenceSessionActive() const;

   262 

   263 

   264         /**

   265          * Closes certain application network presence session.

   266          *

   267          * Asynchronously closes network presence session.

   268          * Result from close is notified to given observer.

   269          *

   270          * - Active network operations from NWSessionSlot are terminated

   271          *   with KErrCancel.

   272          * - Canceling NW session close doesn't stop the actual network

   273          *   session close operation, but merely informs Presence Engine

   274          *   that the client isn't anymore interested from disconnect

   275          *   end status.

   276          *

   277          * Possible errors:

   278          *   - KErrNotFound - NWPresenceSession not open.

   279          *   - Errors specific for real transport

   280          *   - System wide errors

   281          *

   282          *

   283          * Two overloads:

   284          * - CloseNWPresenceSession()

   285          *   Closes the NWPresenceSession if there isn't any other

   286          *   reqistered session owners than the calling client.

   287          *   Note the client CPEngNWSessionSlot2 obejct must have

   288          *   the NWPresenceSession ownership before it can issue this.

   289          *

   290          * - ForceCloseNWPresenceSession()

   291          *   Closes the NWPresenceSession in all cases, event there is

   292          *   other reqistered session owners.

   293          *

   294          * @since 3.0

   295          * @param aObserver The observer to notify from session close results.

   296          *

   297          * @return Result from initiating session close.

   298          *  - KErrNone if session close successfully initiated.

   299          *  - KErrInUse if session close already on going from object.

   300          *  - Else one of system wide error codes.

   301          */

   302         IMPORT_C TInt CloseNWPresenceSession(

   303             MPEngNWSessionOperationObserver2& aObserver );

   304 

   305         IMPORT_C TInt ForceCloseNWPresenceSession(

   306             MPEngNWSessionOperationObserver2& aObserver );

   307 

   308         IMPORT_C void CancelCloseNWPresenceSession();

   309 

   310 

   311 

   312         /**

   313          * Releases the network session ownership from this

   314          * CPEngNWSessionSlot2 handle object.

   315          *

   316          * With this method client can release immiadtely

   317          * active NWPresenceSession ownership. If the released

   318          * ownership is the last one, Presence Engine closes

   319          * down the NWPresenceSession like in case of holding

   320          * application dies.

   321          *

   322          * Similar behaviour takes place if the client

   323          * deletes CPEngNWSessionSlot2 object holding the

   324          * NWSessionOwnership.

   325          *

   326          * @since 3.0

   327          * @return Result:

   328          * - KErrNone if ownership successfully closed.

   329          * - KErrNotSupported if NWPresenceSession not active.

   330          * - In practise clients can ignore errors as the

   331          *   close requests itself succeeds always.

   332          */

   333         IMPORT_C void CloseNWPresenceSessionOwnership();

   334 

   335 

   336 

   337 

   338         //-----------------------------------------------------------------------

   339     public: /* NWPresenceSession ownership storing */

   340 

   341         /**

   342          * Stores the network session ownership from this

   343          * CPEngNWSessionSlot2 handle to Presence Engine.

   344          *

   345          * With this method client can store active NWPresenceSession

   346          * ownership from the client object to Presence Engine

   347          * and thus make the NWPresenceSession to stay open untill

   348          * it is explicitly closed with the ForceCloseNWPresenceSession().

   349          *

   350          * @since 3.0

   351          * @param aOwnerID The NWPresenceSession ownership ID.

   352          * Client can use this ID to later restore the ownership back from

   353          * Presence Engine to client CPEngNWSessionSlot2 object.

   354          *

   355          * @return Result:

   356          * - KErrNone if storing successfully done.

   357          * - KErrNotSupported if NWPresenceSession not active.

   358          * - KErrAlreadyExist if the ownership id exists already.

   359          * - Else one of system wide error codes

   360          */

   361         IMPORT_C TInt StoreNWPresenceSessionOwnership(

   362             const TDesC16& aOwnerID );

   363 

   364 

   365 

   366 

   367         /**

   368          * Restores the network session ownership from Presence Engine

   369          * to this CPEngNWSessionSlot2 handle object.

   370          *

   371          * With this method client restore active NWPresenceSession

   372          * ownership from Presence Engine to CPEngNWSessionSlot2

   373          * handle object and thus make the NWPresenceSession live

   374          * to follow the client live.

   375          *

   376          * @since 3.0

   377          * @param aOwnerID The NWPresenceSession ownership ID.

   378          * Which NWPresenceSession ownership to restore.

   379          *

   380          * @return Result:

   381          * - KErrNone if restoring successfully done.

   382          * - KErrNotSupported if NWPresenceSession not active.

   383          * - KErrNotFound if the ownership id not found.

   384          * - Else one of system wide error codes

   385          */

   386         IMPORT_C TInt RestoreNWPresenceSessionOwnership(

   387             const TDesC16& aOwnerID );

   388 

   389 

   390 

   391 

   392 

   393 

   394         //-----------------------------------------------------------------------

   395     public: /* NWSessionSlot current state */

   396 

   397 

   398         /**

   399          * Gets the network presence session's SAP settings.

   400          *

   401          * Gets the SAP settings as used in presence network

   402          * session open.

   403          *

   404          * @since 3.0

   405          * @param aSAP On the return contains network presence

   406          * session SAP settings. Resets the SAP container

   407          * before adding the settings.

   408          *

   409          * @return Result:

   410          * - KErrNone if settings successfully get.

   411          * - KErrNotFound if no active network presence session.

   412          * - Else one of system wide error codes

   413          */

   414         IMPORT_C TInt GetNWPresenceSessionSap( CWVSAPSettings& aSAP ) const;

   415         IMPORT_C TInt GetNWPresenceSessionSap( CIMPSSAPSettings& aSAP ) const;

   416 

   417 

   418         /**

   419          * Gets NWSessionSlots state.

   420          *

   421          * @since 3.0

   422          * @param aState Last state reported from NWSessionSlot.

   423          * @return  Result:

   424          *  - KErrNone if state successfully get.

   425          *  - Else one of system wide error codes.

   426          */

   427         IMPORT_C TInt GetNWSessionSlotState(

   428             TPEngNWSessionSlotState& aState ) const;

   429 

   430 

   431 

   432 

   433         //-----------------------------------------------------------------------

   434     private: /* Data */

   435 

   436 

   437         //OWN: Implementation

   438         CPEngNWSessionSlot2Imp*     iImp;

   439 

   440 

   441     };

   442 

   443 

   444 #endif //__CPENGNWSESSIONSLOT2_H

   445 

   446 //End of file

   447 

   448 

   449 

   450