/** 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: Handle to NWSessionSlot.**/#ifndef __CPENGNWSESSIONSLOT2_H#define __CPENGNWSESSIONSLOT2_H// INCLUDES#include <E32Base.h>#include <BaDesCa.h>#include <PEngPresenceEngineConsts2.h>//FORWARD DECLARATIONSclass MPEngNWSessionOperationObserver2;class CPEngNWSessionSlot2Imp;class CPEngNWSessionSlotID2;class CWVSAPSettings;class CIMPSSAPSettings;/** * NWSessionSlot option level. * Presence transport query. * @since 3.0 */const TUint KPEngNWSessionSlotTransportQuery = 0x2000;// CLASS DECLARATION/** * Handle to NWSessionSlot. * * NWSessionSlot ties together: * 1. Network presence session * - network presence service is identified by user id * and service address * - NWSessionSlot holds also other SAP settings needed * to connect to network service (IAP ID, user password, etc) * * 2. Network session presence data * - NWSessionSlot is context for certain network * session's presence data * - Presence data consists from * - contact list setings * - contact list data * - attribute list data * - subscribed / fetched presence attributes * - user own attributes * * * NWSessionSlot has a state and event information * describing its current state. * * @lib PEngManager2.lib * @since 3.0 */class CPEngNWSessionSlot2 : public CBase { //----------------------------------------------------------------------- public: /* Construction */ /** * Instantiates NWSessionSlot object. * * Instantiates NWSessionSlot handle object and connects it to * identified Presence Engine side NWSessionSlot. NWSessionSlot * must be a valid, existing slot. * * Errors: * - Requested NWSessionSlot not found: KErrNotFound * - Given NWSessionSlotID malformed: KErrArgument * * @param aNWSessionSlotID The session slot ID to identify the * session slot. * @param aPriority The priority for CPEngNWSessionSlot2 client * side active objects. These active objects are used when * asynchronously delivering events to observers. * * @return New CPEngNWSessionSlot2 instance. */ IMPORT_C static CPEngNWSessionSlot2* NewL( const CPEngNWSessionSlotID2& aNwSessionSlotID, TInt aPriority = CActive::EPriorityStandard ); IMPORT_C static CPEngNWSessionSlot2* NewLC( const CPEngNWSessionSlotID2& aNWSessionSlotID, TInt aPriority = CActive::EPriorityStandard ); /** * Destructor. * Virtual by CBase. */ ~CPEngNWSessionSlot2(); private: CPEngNWSessionSlot2(); //----------------------------------------------------------------------- public: /* NW Session Slot configuration */ /** * Gets the NWSessionSlotID. * * @since 3.0 * @param aNWSessionSlotID On the return contains the NWSessionSlotID * of connected NWSessionSlot. * @return Result from NWSessionSlotID get. One of a system * wide error codes. */ IMPORT_C TInt GetNWSessionSlotID( CPEngNWSessionSlotID2& aNWSessionSlotID ) const; /** * Generic getter to access NWSessionSlot options. * * Generic getters to access NWSessionSlot options. * Used for example to get underlying network session * capabilities. See PEngWVServices2.h for more info about * WV network capabilities. * * @since 3.0 * @param aOptionName Constant which identifies an option. * @param aOptionLevel Constant which identifies level of an option. * @param aOption On the return contains actual option value. * @return Result from option get. Might be a system * wide error code or error code specific to option. */ IMPORT_C TInt GetOption( TUint aOptionName, TUint aOptionLevel, TDes8& aOption ); //----------------------------------------------------------------------- public: /* Network session start and ownership gaining */ /** * Tests is the NWPresenceSession open already active. * * @since 3.0 * @return ETrue NWPresenceSession open is active. * Else EFalse. */ IMPORT_C TBool IsOpenNWPresenceSessionActive() const; /** * Opens application network presence session. * * Asynchronously opens network presence session for * application and connects it to given presence network * service. Result from open is notified to given observer. * * - If underlying network CSP session is already open, * joins the NWSessionSlot to existing CSP session if SAP * settings match. * - At successful login the client CPEngNWSessionSlot2 instance * becomes a NWPresenceSession ownership handle. If client * dies or the handle is deleted, the opened NWPresenceSession * is automaticly closed, if there isn't other registered * session owners. Client can "store" the ownership to system * if it doesn't want the automatic close behaviour. * See StoreNWPresenceSessionOwnership(). * - Performs network session capability query. Capabilities * can be asked from NWSessionSlot after login. * * Possible errors: * - KErrAlreadyExist - NWPresenceSession already open * - Errors specific for real transport * - System wide errors * * @since 3.0 * @param aSAP The SAP settings to use for NWPresenceSession * Server address and user ID must match to NWSessionSlotID. * Overloaded version for CWVSAPSettings and CIMPSSAPSettings. * * @param aObserver The observer to notify from session open results. * * @return Result from initiating session open. * - KErrNone if session open successfully initiated. * - KErrInUse if session open already on going from object. * - Else one of system wide error codes. */ IMPORT_C TInt OpenNWPresenceSession( const CWVSAPSettings& aSAP, MPEngNWSessionOperationObserver2& aObserver ); IMPORT_C TInt OpenNWPresenceSession( const CIMPSSAPSettings& aSAP, MPEngNWSessionOperationObserver2& aObserver ); IMPORT_C void CancelOpenNWPresenceSession(); /** * Gains the network session ownership to this * CPEngNWSessionSlot2 handle object. * * With this method client can get active NWPresenceSession * ownership to additional handle object. Can be used * in cases where several applications want to control * NWPresenceSession lifetime with their own lifetime. * * @since 3.0 * @return Result: * - KErrNone if ownership gaining successfully done. * - KErrNotSupported if NWPresenceSession not active. * - Else one of system wide error codes */ IMPORT_C TInt OpenNWPresenceSessionOwnership(); //----------------------------------------------------------------------- public: /* Network session stop and ownership closing */ /** * Tests is the NWPresenceSession close already active. * * @since 3.0 * @return ETrue NWPresenceSession close is active. * Else EFalse. */ IMPORT_C TBool IsCloseNWPresenceSessionActive() const; /** * Closes certain application network presence session. * * Asynchronously closes network presence session. * Result from close is notified to given observer. * * - Active network operations from NWSessionSlot are terminated * with KErrCancel. * - Canceling NW session close doesn't stop the actual network * session close operation, but merely informs Presence Engine * that the client isn't anymore interested from disconnect * end status. * * Possible errors: * - KErrNotFound - NWPresenceSession not open. * - Errors specific for real transport * - System wide errors * * * Two overloads: * - CloseNWPresenceSession() * Closes the NWPresenceSession if there isn't any other * reqistered session owners than the calling client. * Note the client CPEngNWSessionSlot2 obejct must have * the NWPresenceSession ownership before it can issue this. * * - ForceCloseNWPresenceSession() * Closes the NWPresenceSession in all cases, event there is * other reqistered session owners. * * @since 3.0 * @param aObserver The observer to notify from session close results. * * @return Result from initiating session close. * - KErrNone if session close successfully initiated. * - KErrInUse if session close already on going from object. * - Else one of system wide error codes. */ IMPORT_C TInt CloseNWPresenceSession( MPEngNWSessionOperationObserver2& aObserver ); IMPORT_C TInt ForceCloseNWPresenceSession( MPEngNWSessionOperationObserver2& aObserver ); IMPORT_C void CancelCloseNWPresenceSession(); /** * Releases the network session ownership from this * CPEngNWSessionSlot2 handle object. * * With this method client can release immiadtely * active NWPresenceSession ownership. If the released * ownership is the last one, Presence Engine closes * down the NWPresenceSession like in case of holding * application dies. * * Similar behaviour takes place if the client * deletes CPEngNWSessionSlot2 object holding the * NWSessionOwnership. * * @since 3.0 * @return Result: * - KErrNone if ownership successfully closed. * - KErrNotSupported if NWPresenceSession not active. * - In practise clients can ignore errors as the * close requests itself succeeds always. */ IMPORT_C void CloseNWPresenceSessionOwnership(); //----------------------------------------------------------------------- public: /* NWPresenceSession ownership storing */ /** * Stores the network session ownership from this * CPEngNWSessionSlot2 handle to Presence Engine. * * With this method client can store active NWPresenceSession * ownership from the client object to Presence Engine * and thus make the NWPresenceSession to stay open untill * it is explicitly closed with the ForceCloseNWPresenceSession(). * * @since 3.0 * @param aOwnerID The NWPresenceSession ownership ID. * Client can use this ID to later restore the ownership back from * Presence Engine to client CPEngNWSessionSlot2 object. * * @return Result: * - KErrNone if storing successfully done. * - KErrNotSupported if NWPresenceSession not active. * - KErrAlreadyExist if the ownership id exists already. * - Else one of system wide error codes */ IMPORT_C TInt StoreNWPresenceSessionOwnership( const TDesC16& aOwnerID ); /** * Restores the network session ownership from Presence Engine * to this CPEngNWSessionSlot2 handle object. * * With this method client restore active NWPresenceSession * ownership from Presence Engine to CPEngNWSessionSlot2 * handle object and thus make the NWPresenceSession live * to follow the client live. * * @since 3.0 * @param aOwnerID The NWPresenceSession ownership ID. * Which NWPresenceSession ownership to restore. * * @return Result: * - KErrNone if restoring successfully done. * - KErrNotSupported if NWPresenceSession not active. * - KErrNotFound if the ownership id not found. * - Else one of system wide error codes */ IMPORT_C TInt RestoreNWPresenceSessionOwnership( const TDesC16& aOwnerID ); //----------------------------------------------------------------------- public: /* NWSessionSlot current state */ /** * Gets the network presence session's SAP settings. * * Gets the SAP settings as used in presence network * session open. * * @since 3.0 * @param aSAP On the return contains network presence * session SAP settings. Resets the SAP container * before adding the settings. * * @return Result: * - KErrNone if settings successfully get. * - KErrNotFound if no active network presence session. * - Else one of system wide error codes */ IMPORT_C TInt GetNWPresenceSessionSap( CWVSAPSettings& aSAP ) const; IMPORT_C TInt GetNWPresenceSessionSap( CIMPSSAPSettings& aSAP ) const; /** * Gets NWSessionSlots state. * * @since 3.0 * @param aState Last state reported from NWSessionSlot. * @return Result: * - KErrNone if state successfully get. * - Else one of system wide error codes. */ IMPORT_C TInt GetNWSessionSlotState( TPEngNWSessionSlotState& aState ) const; //----------------------------------------------------------------------- private: /* Data */ //OWN: Implementation CPEngNWSessionSlot2Imp* iImp; };#endif //__CPENGNWSESSIONSLOT2_H//End of file