/*

 * 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