diff -r 000000000000 -r 094583676ce7 inc/CPEngNWSessionSlot2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/CPEngNWSessionSlot2.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,450 @@ +/* +* 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 +#include +#include + + + + +//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 + + + +