/*
* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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: 
* Server-side classes which are required to implement a session counting server.
*
*/


/**
 @file
 @publishedPartner
 @released
*/

#ifndef SCSSERVER_H
#define SCSSERVER_H

#include <e32base.h>

#include <scs/scsclient.h>
#include <scs/scscommon.h>

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
#include "scsserverconstants.h"
#endif

// -------- error handling --------


const TInt KErrScsAsyncAlreadyQueued = -5702;	///< Tried to re-queue an outstanding request.



// forward declarations
class CScsServer;
class CScsSession;
class CScsSubsession;

class CShutdownTimer : public CTimer
/**
	When an instance of this class is constructed it is given a delay period.
	If the object runs to completion, i.e. if it is not cancelled, then it stops
	the active scheduler, which has the effect of terminating the server.
*/
	{
public:
	static CShutdownTimer* NewL(TInt aDelayUs);

	void Restart();

	void ImmediateTimeoutNextRestart();

private:
	CShutdownTimer(TInt aDelayUs);

	// implement CTimer
	virtual void RunL();

private:
	TInt iDelayUs;			///< Timer delay in microseconds.
	TBool iImmediateTimeoutNextRestart;
	};

class CAsyncRequest : public CActive
/**
	An outstanding request on the server side.	A subclass should
	be created for each type of outstanding request.

	This class is implemented as an active object, because it is
	anticipated that some asynchronous requests can be implemented
	simply by completing the client request when a TRequestStatus
	completes.	The implementor can override this behavior by
	re-implementing RunL, e.g. to free some resources before completing
	the request.  If they do so, they must call CompleteAndMarkForDeletion to 
	complete the client request and mark this object for deletion (alternatively
	they can simply call CAsyncRequest::RunL from their RunL).

	This class cannot, however, anticipate the cancellation
	mechanism.	The implementor must implement DoCancel for that.
	DoCancel should not delete the client request or mark this object
	for deletion.

	When the implementor has allocated an instance of this
	class, they must add it to the session by calling CAsyncRequest::TransferToScsFrameworkL.
	The second-phase constructor must not  leave between that and calling
	SetActive.

	These objects are cancelled and destroyed when the
	client-side session / subsession sends a cancel command.

	@see CScsSession::AddAsyncRequestL
*/
	{
public:
	IMPORT_C CAsyncRequest(CScsSession* aSession, CScsSubsession* aSubsession, const RMessage2& aMessage);
	
	void CancelCompleteAndMarkForDeletion();	// explicit cancel request
	void MarkForDeletion();						// session close
	IMPORT_C virtual void DoCleanup();	// Cancel this request
	
	IMPORT_C void TransferToScsFrameworkL();
protected:
	
	IMPORT_C void CompleteAndMarkForDeletion(TInt aError);
	
	// implement CActive
	IMPORT_C virtual void RunL();

	// override CActive
	IMPORT_C virtual TInt RunError(TInt aError);
		
public:
	/** Session on which this request is queued.  NULL if completed. */
	CScsSession* iSession;
	/** Subsession on which this request is queued.	 NULL if session-relative. */
	CScsSubsession* iSubsession;
	/** Outstanding message to complete. */
	const RMessagePtr2 iMessagePtr2;
	/** Identifies outstanding request. */
	TInt iFunction;
	};

class CScsSubsession : public CObject
/**
	If the server implementation supports subsessions, they must
	derive from this class.

	WARNING: Because this class derives from CObject you must not simply delete
	an instance of a class derived from this class (ie. your subsession), instead you MUST
	Close() it. 

	In practise this probably means you need a ConstructL like this:-
	CFred *self = new(ELeave) CFred(....);
	CleanupClosePushL(*self); // Note use of CleanupClosePushL and of *self
	self->ConstructL(...);
	CleanupStack::Pop(self); // Note use of *self instead of self
 */
	{
public:
	/**
		SCS routes subsession messages to this function; the session
		object does not have to decode them	 itself.

		@param	aFunction		Implementation function, i.e. the function
								identifier with the SCS field removed.
		@param	aMessage		Standard server message object.
		@return ETrue means complete client request now.
	 */
	virtual TBool DoServiceL(TInt aFunction, const RMessage2& aMessage) = 0;

protected:
	IMPORT_C CScsSubsession(CScsSession &aSession);
	
public:
	// Note this is setup by the constructor, before the derived class
	// ConstructL is called.
	CScsSession& iSession;			///< Owning session.
	};

class CScsSession : public CSession2
/**
	When this session object is destroyed (because the client-server session
	has closed,) this notifies the server object which decrements the session
	count.	Therefore, the server can be shut down after an inactivity
	period during which there are no open sessions.

	This object also frees any remaining subsession objects when it is closed.
*/
	{
protected:
	IMPORT_C void ConstructL();
	IMPORT_C virtual ~CScsSession();
	
	// implement CSession2
	IMPORT_C virtual void ServiceL(const RMessage2& aMessage);
	// override CSession2
	IMPORT_C virtual void ServiceError(const RMessage2& aMessage, TInt aError);
	IMPORT_C void CloseAllSubsessionsL();
	
	// asynchronous requests
	//IMPORT_C void CompleteAsyncRequest(CAsyncRequest* aAsyncRequest, TInt aReason);
		
private:
	/**
		This function is called from ServiceL after it has removed the
		SCS-specific field and handled any other messages.	I.e., it is
		called for functions which really require the session as opposed
		to subsession commands or debugging commands such as heap failure.

		@param	aFunction		Implementation function, i.e. the function
								identifier with the SCS field removed.
		@param	aMessage		Standard server message object.
		@return ETrue if client message should be completed now.
	 */
	virtual TBool DoServiceL(TInt aFunction, const RMessage2& aMessage) = 0;

	void PreCloseSession();

	IMPORT_C virtual CScsSubsession* DoCreateSubsessionL(TInt aFunction, const RMessage2& aMessage);
	
	// subessions
	CScsSubsession* GetSubsessionL(const RMessage2& aMessage);
	void DeleteSubsessionContainers();
	
	void CreateSubsessionL(TInt aFunction, const RMessage2& aMessage);
	void CloseSubsessionL(const RMessage2& aMessage);
	TBool CallSubsessionFunctionL(TInt aFunction, const RMessage2& aMessage);
	void CancelAsyncSubsessionRequestL(TInt aFunction, const RMessage2& aMessage);
	
	// asynchronous requests (support)
	CAsyncRequest* FindSessionAsyncRequest(TInt aFunction);
	void CancelAsyncSessionRequestL(TInt aFunction);

private:
	/**
		Number of open subsessions before a new one is created.	 This is used
		to manage cleanup if the subsession cannot be created.
	 */
	TInt iPreCreateSubsessionCount;

	CObjectCon* iSsObjects;				///< Currently open subsessions.
	CObjectIx* iSsHandles;				///< Maps handles to open subsessions.
	
public:
	IMPORT_C CScsSession(CScsServer &aServer);
	// This duplicates the iServer/Server() code in the base class,
	// BUT this variable IS setup before derived class ConstructL is
	// called and is NOT const. This trades off 4 bytes of memory
	// against making the code cleaner and more consistent....
	CScsServer& iServer;			///< Owning server.
	};

/**
	Pass to CScsServer::CancelOutstandingRequests to mean all requests
	associated with a session or its subsessions.
 */
CScsSubsession*const KWildSubsession = reinterpret_cast<CScsSubsession*>(~0);

class CScsServer : public CPolicyServer
/**
	The main server object allocates sessions.	It also uses
	a shutdown timer to stop the server when there have been no
	open sessions for a set period.

	The implementor must define a subclass which returns session
	objects of the appropriate type.
 */
	{
public:
	IMPORT_C virtual ~CScsServer();

	void IncrementSessionCount();
	void DecrementSessionCount();
	inline TInt SessionCount() const;

	IMPORT_C void ShutdownWhenIdleL();

	// asynchronous requests
	void AddAsyncRequestL(CAsyncRequest* aAsyncRequest);
	void CancelAsyncRequest(
		CScsSession* aSession, CScsSubsession* aSubsession, TInt aFunction);
	
	void CancelOutstandingRequests(CScsSession* aSession, TBool aCompleteClientRequests);
	void CancelOutstandingRequests(CScsSession* aSession, CScsSubsession* aSubsession, TBool aCompleteClientRequests);

	/**
		This function is called just before the SCS framework marks the heap for OOM 
		testing and just before checking the heap.

		Typically this function should compact any arrays and free objects which change size and can
		not be compacted back to the same level.
	*/
	IMPORT_C virtual void DoPreHeapMarkOrCheckL();

	/**
		This function is called just after the heap has either been marked or checked (which is just 
		after DoPreHeapMarkOrCheck).

		Typically this function should re-create any objects which had to be freed by DoPreHeapMarkOrCheck.
	*/
	IMPORT_C virtual void DoPostHeapMarkOrCheckL();

	enum TFunctionRanges
	/**
	   Function ranges to be used when configuring the server security via
	   a CPolicyServer::TPolicy object.
	   
	   Session/sSubsession function codes will be ORed into the
	   EBaseSession/EBaseSubSession ranges.
	   
	   Values from EBaseMustAllow, upwards, are used internally and must be allowed.
	   
	   If there are multiple subsession types (with different function
	   code values), then codes must be be different for each subsession
	   (this restriction only applies if using the CPolicyServer::TPolicy
	   mechanism to configure server security).
	   
	   WARNNIG: These ranges MUST match the values in scscommon.h TScsFunction.
	*/
	{
		EBaseSession	= 0x01000000,
		EBaseSubSession = 0x02000000,
		EBaseMustAllow	= 0x03000000 //< Must allow from EBaseMustAllow upwards
	};
	
	static TInt StripScsFunctionMask(TInt aFunctionId) { return aFunctionId & ~ScsImpl::KScsFunctionMask;}

protected:
	IMPORT_C CScsServer(const TVersion& aVersion, CActive::TPriority aPriority = CActive::EPriorityStandard);
	IMPORT_C CScsServer(const TVersion& aVersion, const CPolicyServer::TPolicy& aPolicy, CActive::TPriority aPriority = CActive::EPriorityStandard);
	IMPORT_C void ConstructL(TInt aShutdownPeriodUs);

	IMPORT_C void DisableShutdownTimer();
	IMPORT_C void EnableShutdownTimerL(TInt aShutdownPeriodUs);


	// implement CServer2
	IMPORT_C virtual CSession2* NewSessionL(const TVersion& aVersion, const RMessage2& aMessage) const;

	/**
		NewSessionL checks that this server supports the version which is
		requested by the client.  If that is so, then it calls this function
		to allocate a new session object.

		@param	aMessage		Connection message, as passed to NewSessionL.
		@return					New session object.	 This is owned by the kernel,
								which will delete it when the session is closed.
	 */
	virtual CScsSession* DoNewSessionL(const RMessage2& aMessage) = 0;

private:
	// asynchronous requests
	CAsyncRequest* FindAsyncRequest(
		CScsSession* aSession, CScsSubsession* aSubsession, TInt aFunction);
	
	static TInt RemoveCompletedRequests(TAny* aPtr);
	void RemoveCompletedRequests();

private:
	/**
		This server's version.	It is compared against client's requested version
		when the client attempts to make a connection.
	 */
	const TVersion iVersion;

	/** Number of open sessions.  Used to start and cancel the shutdown timer. */
	TInt iSessionCount;

	/**
		Shutdown timer, started when there are no open sessions, cancelled when
		the first session is created.
	 */
	CShutdownTimer* iShutdownTimer;

	
public:
	/**
		Generates instances of CObjectCon, for each session to host its subsessions.
		Public because must be accessible to session objects.
	 */
	CObjectConIx* iContainerIndex;
	
	/** Currently outstanding requests. */
	RPointerArray<CAsyncRequest> iAsyncRequests;
	
	/** Runs to remove completed requests from iAsyncRequests. */
	CAsyncCallBack* iAsyncCleanup;
	};

inline TInt CScsServer::SessionCount() const
	{
	return iSessionCount;
	}



// -------- startup --------

/**
	The server executable must implement a factory function with this
	signature and pass it to StartScsServer to allocate and start the server.
 */	
typedef CScsServer* (*TScsServerFactory)();

IMPORT_C TInt StartScsServer(TScsServerFactory aServerFactoryLC);


#endif	// #ifndef SCSSERVER_H