/*
* 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: 
* Information shared between SCS client and server implementations,
* and with the subclass implementations, but not with the client API user.
*
*/


/**
 @file
 @internalTechnology
 @released
*/

#ifndef SCSCOMMON_H
#define SCSCOMMON_H

#include <e32std.h>

#ifndef BULLSEYE_OFF
#ifdef _BullseyeCoverage
#define BULLSEYE_OFF "BullseyeCoverage save off";
#define BULLSEYE_RESTORE "BullseyeCoverage restore";
#else
#define BULLSEYE_OFF 
#define BULLSEYE_RESTORE 
#endif
#endif

namespace ScsImpl
	{
	/** 
		Bit position of SCS code in function code.

		Do not change - Some of the codes based off this definition
		ARE public.
	*/
	const TInt KScsFunctionPos = 24;
	
	/** 
		Mask used to extract SCS commands.

		Do not change - Some of the codes based off this definition
		ARE public.
	*/
	const TInt KScsFunctionMask = 0xFF000000;
	
	enum TScsFunction
	/**
		Bits 31:24 of the function code are reserved for SCS fields.
		The values below should be or'd into the code that is sent to
		the server, on the client side.
		
		The recognized values intentionally exclude zero, to ensure
		that a field is added on the client side.
	 */
		{
		/** 
			Function should be handled by session's DoServiceL.

			This value is effectively PUBLIC because the range used is
			described by defines in scsserver.h (used for configuring
			server security).
		*/
		ECallSessionFunc = 1 << KScsFunctionPos,
		
		/**
			The SCS sends the lower bits of the function code to the subsession's
			(not the session's) ServiceL implementation.

			The session's implementation of [Do]ServiceL is not involved.

			This value is effectively PUBLIC because the range used is
			described by defines in scsserver.h (used for configuring
			server security).
		 */
		ECallSubsessionFunc = 2 << KScsFunctionPos,

		/**
			This message is send with no function identifier or
			IPC arguments just before the session is closed.  Although
			not necessary, it will cancel any outstanding requests on
			the session or its subsessions with KErrCancel, so if the
			client has any outstanding requests they will still get
			completed.
		 */
		EPreCloseSession = 3 << KScsFunctionPos,
		
		/**
			Cancel an asynchronous session-relative function.  The low
			bits of the function code should be the same as the original
			function code.  E.g. if the function was set up with
			ENoScsFunction | X then it would be cancelled with ECancelSessionFunction | X.

			The session's implementation of [Do]ServiceL is not involved.
		 */
		ECancelSessionFunc = 4 << KScsFunctionPos,

		/**
			Tells the server that this function will create a new subsession.
			The low bits can be interpreted by the implementation to indicate
			a type of subsession.
		 */
		ECreateSubsession = 5 << KScsFunctionPos,
		/**
			This SCS code should be used on its own.  Any information in the
			lower bits will be ignored.
		 */
		ECloseSubsession = 6 << KScsFunctionPos,

		/**
			Similar to ECancelSessionFunction, this cancels an asynchronous
			request on a subsession object.  The request will be completed with
			KErrCancel.

			The subsession's implementation of ServiceL is not involved.

			@see ECancelSessionFunction
		 */
		ECancelSubsessionFunc = 7 << KScsFunctionPos,
		
		/**
			Only supported in debug builds, this function starts a server-side
			heap mark with __UHEAP_MARK and sets a deterministic failure rate.
			This function should only be used by RScsClientBase::SetServerHeapFail.

			@see EUHeapResetFail
			@see RScsClientBase::SetServerHeapFail
		 */
		EUHeapSetFail = 8 << KScsFunctionPos,

		/**
			Only supported in debug builds, this function ends the server-side
			heap mark set up with EUHeapSetFail, with __UHEAP_MARKEND, and resets
			the heap failure rate.  This function should only be used by
			RScsClientBase::ResetServerHeapFail.

			@see EUHeapSetFail
			@see RScsClientBase::ResetServerHeapFail
		 */
		EUHeapResetFail = 9 << KScsFunctionPos,

		/**
			Intended for debug use, but also present in production builds.

			Returns the PID of the server. This is a number, not a
			handle, so does not impact security.

		 */
		EGetServerPid = 10 << KScsFunctionPos,

		/**
			Intended for debug use, but also present in production builds.

			This call causes a server which has an inactivity shutdown
			timer to shutdown immediately the next time it is
			idle. This is just adjusts the timing of existing
			functionality, so is not believed to impact security.

			If the server has a shutdown timer, then a flag is set
			which causes the server to immediately exit the next time
			it becomes idle.

			If the server does not have a shutdown timer, then the
			calls fails with KErrNotSupported.
		 */
		EShutdownAsap = 11 << KScsFunctionPos,
		
		/**
			This value is not used by the server implementation.  It is provided
			for test code to confirm the server handles an uncrecognized instruction
			correctly, by failing with KErrNotSupported.
		 */
		EScsUnused = 0x20 << KScsFunctionPos
		};
	
	inline void ExtractScsAndImplFunctions(const RMessage2& aMessage, TScsFunction* aScsFunc, TInt* aImplFunc);
	inline TBool ScsFieldUsed(TInt aFunction);

	/**
		SCS clients are panicked with this category when invalid
		input to the server is detected.

		@see TClientPanic
	 */
	_LIT(KScsClientPanicCat, "SCS-Client");

	enum TScsClientPanic
	/**
		Reasons why the SCS server might panic its clients.

		@see KScsClientPanicCat
	 */
		{
		EScsClBadDesc = 0,				///< Client provided a bad descriptor as an IPC argument.
		EScsClBadHandle = 1,			///< Client passed a bad subsession handle.
		EScsClAsyncAlreadyQueued = 2,	///< Client attempted to requeue an outstanding request.
		
		/** No-arg session-relative function identifier used reserved SCS bits. */
		EScsClNoArgsSessUsedScs = 4,
		
		/** Arg session-relative function identifier used reserved SCS bits. */
		EScsClArgsSessUsedScs = 5,
		
		/** Arg session-relative async function identifier used reserved SCS bits. */
		EScsClArgsSessAsyncUsedScs = 6,
		
		/** Session-relative cancel function identifier used reserved SCS bits. */
		EScsClCancelSessUsedScs = 7,
		
		/** No-arg subsession-relative function identifier used reserved SCS bits. */
		EScsClNoArgsSubsessUsedScs = 16,
		
		/** Arg subsession-relative function identifier used reserved SCS bits. */
		EScsClArgsSubsessUsedScs = 17,
		
		/** Arg subsession-relative async function identifier used reserved SCS bits. */
		EScsClArgsSubsessAsyncUsedScs = 18,
		
		/* Subsesion-relative cancel function identifier used reserved SCS bits. */
		EScsClCancelSubsessUsedScs = 19
		};
	
	// defined only in client-side implementation
	void ClientSidePanic(ScsImpl::TScsClientPanic aReason);
	}	// namespace ScsImpl

#include <scs/scscommon.inl>

#endif	// #ifndef SCSCOMMON_H