/*

* Copyright (c) 2002 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:  Sub session of the Presence server

*  				 It is used to maintain one session slot.

*

*/

#ifndef __RPENGSESSIONHOLDER_H__

#define __RPENGSESSIONHOLDER_H__

//  INCLUDES

#include <e32def.h>

#include "RPEngManagerClient.h"

// FORWARD DECLARATIONS

class RPEngManagerClient;

class TPEngWVCspServicesTree2;

// CLASS DECLARATION

/**

 *  Sub-session of the Presence Server

 *  It is used to maintain one session slot.

 *

 *  @lib PEngClient2

 *  @since 3.0

 */

class RPEngSessionHolder : public RSubSessionBase

    {

    public:		// Constructors and destructors

        /**

         * Destructor.

         */

        IMPORT_C  ~RPEngSessionHolder( void );

        /**

         * C++ default constructor.

         */

        IMPORT_C	RPEngSessionHolder( void );

    public:		// Connect close operations

        /**

         *	Connect this sub-session to the Presence Server

         *

         *	Client is connected to the server with defined session Id

         *	and application Id

         *

         *  @since 3.0

         *  @param aSessionId packed session slot Id

         *	@param aAppId application Id

         *	@param aManagerClient main session client

         *  @return KErrNone if connected or system wide error code

         */

        IMPORT_C TInt Connect(	const TDesC8& aSessSlotId,

                               const TDesC16& aAppId,

                               RPEngManagerClient& aManagerClient );

        /**

         *	Closes sub session to the Presence server

         *

         *	This can be used also for CleanUpStack support

         *	By default this will cause detach of the sub-session holder

         *	on the server side

         *

         *  @since 3.0

         */

        IMPORT_C void Close();

    public:		// New Opening methods

        /**

         *	Asynchronous request to open new network session

         *

         *

         *	LogIn fails if there already such a session active on

         *	the server side.

         *	Session is specified by the information passed at holder

         *	construction.

         *	If client still wants to get shared owner ship of the existing

         *	active session, Attach method has to be used instead

         *	Once LogIn is completed successfully this session holder

         *	becomes reference to the such a session and its

         *	lifetime is bound with it. How closing of this session

         *	holder affects session itself depends on the function which is

         *	used for closing of this handler. See:

         *	ForceLogOut(), Detach(), LeaveAlive()

         *

         *

         *	@since 3.0

         *	@param aLogInData buffer with the logIn data information

         *	@param aStatus - TRequestStatus, where server will

         *			signal completing of the LogIn request

         *	@return KErrNone if request went fine to server, otherwise

         *				system wide error code

         */

        IMPORT_C TInt LogIn( const TDesC8& aLogInData,

                             TRequestStatus& aStatus );

        /**

         *	Cancel LogIn request

         *	@since 3.0

         */

        IMPORT_C void CancelLogIn();

        /**

         *	Synchronous request to attach holder to existion session

         *

         *	Session holder is attached to the existing active session

         *	on the server.

         *	Session is specified by the information passed at holder

         *	construction.

         *

         *  @since 3.0

         *  @return KErrNone if request went fine to server, otherwise

         *				system wide error code

         */

        IMPORT_C TInt Attach();

        /**

         *	Synchronous request to attach holder to existion session

         *

         *	This will attach holder to the session which is active and

         *	was left to be active with specified process name.

         *	Once Holder is attached with the process name, process name

         *	is removed on the server side from the list of reserved

         *	process names which are reserving session to be opened

         *	even those processes are not alive.

         *	Session is specified by the information passed at holder

         *	construction.

         *

         *  @since 3.0

         *  @param aProcessName process name

         *  @return KErrNone if request went fine to server, otherwise

         *				system wide error code

         */

        IMPORT_C TInt Attach( const TDesC& aProcessName );

    public:	// New closing functions

        /**

         *	Asynchronous request to force network session close

         *

         *  Network session is closed on the server side for all

         *  application Ids

         *

         *	@since 3.0

         *	@param aStatus - TRequestStatus, where server will

         *			signal completing of the request

         *	@return KErrNone if request went fine to server, otherwise

         *				system wide error code

         */

        IMPORT_C TInt ForceLogOut( TRequestStatus& aStatus );

        /**

         *	Cancel LogOut request

         *

         *	@since 3.0

         */

        IMPORT_C void CancelLogOut();

        /**

         *	Detach Session holder

         *

         *	This function detaches session holder from active session

         *	on the server, it can result in closing of the session if

         *	this holder was last one using the session, therefore

         *	This function is asynchronous, though in most cases it

         *	will be completed immediately.

         *

         *  @since 3.0

         *	@param aStatus - TRequestStatus, where server will

         *			signal completing of the request

         *	@return KErrNone if request went fine to server, otherwise

         *				system wide error code

         */

        IMPORT_C TInt Detach( TRequestStatus& aStatus );

        /**

         *	Cancel Detach request

         *

         *	@since 3.0

         */

        IMPORT_C void CancelDetach();

        /**

         *	Leave session alive closing call

         *

         *	This call will leave session opened with reserved session

         *	for passed Process Name, untill this process name is not

         *	attached again some holder, session will stay active

         *	It should be used with caution, since it can leave to

         *	opened session without any client.

         *	How ever id client wants to disconnect from the session

         *	but keep session alive for next connection, this it the

         *	way to get job done.

         *

         *  @since 3.0

         *  @param aProcessName Process name to reserve session for

         *	@return KErrNone if request went fine to server, otherwise

         *				system wide error code

         */

        IMPORT_C TInt LeaveAlive( const TDesC& aProcessName );

        /**

         *  Session slot capabilities tree

         *

         *	retrieves Session slot's capability tree

         *	Function

         *

         *  @since 3.0

         *  @param aService tree to be filled with values of the session

         *			slot.

         *	@return KErrNone if session is opened and request to

         *		  server was successful, otherwise system wide error code

         */

        IMPORT_C TInt GetServiceTree(

            TPEngWVCspServicesTree2& aServiceTree );

        /**

         *  Session slot Log-In data

         *

         *	Returns log in data which were used for session slot opening

         *

         *  @since 3.0

         *  @param aLogInData buffer which will be on the return filled

         *			with log in data.

         *	@return KErrNone if session is opened and request to

         *		  server was successful, otherwise system wide error code

         */

        IMPORT_C TInt LogInData( HBufC8*& aLogInData );

    private:	// Data

        /// OWN: Flag is client is connected or not

        TBool						iConnected;

        /// OWN: Size of the Log in data buffer

        TInt						iLogInData;

    };

#endif      //  __RPENGSESSIONHOLDER_H__