/*
* 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 DECLARATIONS
class 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