// Copyright (c) 2002-2010 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:
// Contains the Domain Manager interface for clients providing policy 
// information. Typically this is the same client that acts in the 
// "Domain Controller" role.
//
// There are two versions of the policy API - the original V1 and the new V2.
// V2 builds upon V1 and specifies the states which clients are allowed to defer 
// their transition timeout if they have not finished, up to a max number of 
// times. This is part of the Domain Manager Transition Monitoring feature.
//
//
// WARNING: This file contains some APIs which are internal and are subject
//          to change without notice. Such APIs should therefore not be used
//          outside the Kernel and Hardware Services package.
//

#ifndef __DOMAIN_POLICY_H__
#define __DOMAIN_POLICY_H__

#include <e32std.h>

#include <domaindefs.h>


/**
Defines the characteristics of a domain.
*/
struct TDmDomainSpec
	{
	/**	The 16-bit domain identifier */
	TDmDomainId					iId;
	
	/**	The domain identifier of the domain's parent */
	TDmDomainId					iParentId;

	/**	The security capability required to join this domain */
	TStaticSecurityPolicy		iJoinPolicy;
	
	/**	The initial state of the domain after construction */
	TDmDomainState				iInitState;
	
	/**	The total time allowed for the domain to complete a state transition.
	Members of the domain must acknowledge a transition within this time.
	Measured in microseconds. */
	TUint32						iTimeBudgetUs;
	};

#define TDM_DOMAIN_SPEC_END  {KDmIdNone, KDmIdNone,	_INIT_SECURITY_POLICY_PASS,	0, 0}



/**
Defines the overall traversal and failure policy for a particular 
domain hierarchy and is returned by DmPolicy::GetPolicy().
Note the failure policy can be overridden for individual 
states in V2 policies. 

@see TDmTransitionFailurePolicy
*/
class TDmHierarchyPolicy
	{
public:
	/** Direction of traversal if target state is after current state */
	TDmTraverseDirection iPositiveTransitions;
	
	/**	Direction of traversal if target state is before current state */
	TDmTraverseDirection iNegativeTransitions;
	
	/** Policy which outlines the action upon transition failure */
	TDmTransitionFailurePolicy iFailurePolicy;
	};



/**
Defines the characteristics of a state and is used by entry points introduced
in version 2 of the policy API. The structure itself is also versioned with V1 
in use with version 2 policy libraries. 

Policy providers provide an object of this type for each state they want to:
- enable the Transition Monitoring feature or/and
- override the default failure policy

Enabling transition monitoring will allow trusted clients to receive more time
to complete their work before final acknowledgment. Enable transition 
monitoring to ensure a fair completion of the transition e.g. shutdown system.
Where transition monitoring is enabled the Domain level timer is not used
and iTimeBudgetUs provided in TDmDomainSpec is ignored.

The global failure policy is returned by DmPolicy::GetPolicy() and in V1 
policies this applies to all state transitions. iFailurePolicy in this 
structure allows different failure policies for different state transitions. 

@see DmPolicy::GetStateSpec()
*/
struct SDmStateSpecV1
	{
	/**	The destination state of the transition */
	TDmDomainState		iState;
	
	/** Transition Monitoring: member transition timeout granularity, in 
	milliseconds, e.g. 200ms. Set to 0 to not use transition monitoring for 
	this state. */
	TInt16				iTimeoutMs;	
		
	/** Transition Monitoring: maximum number of times a domain member may be 
	granted an additional timeout period. Set to 0 when transition 
	monitoring not used for this state. */	
	TInt16				iDeferralLimit;	
	
	/** Specifies the failure policy for transitions to the target state, see
	TDmTransitionFailurePolicy. Overrides the global value returned by 
	the policy function DmPolicyGetPolicy(). 
	Set to ETransitionFailureUsePolicyFromOrdinal3 if override not required. */	
	TInt16			    iFailurePolicy;
	};
	
const TInt KSDmStateSpecV1 = 1;



/**
Defines the function type for a static function that is implemented by
a device's domain policy DLL at ordinal 1.
The domain manager uses this function to access the domain
hierarchy specification. The pointer returned must point to an array of
TDmDomainSpec objects where the last object in the array is defined
using the END macro, as shown below.
@code
	. . .
	TDM_DOMAIN_SPEC_END
	};
@endcode

The implementation should return NULL if it is unable to supply the requested
information due to an error. This will abort policy loading and hierarchy 
creation. 
The implementation must never panic or leave in any way.

@see DmPolicy
*/
typedef const TDmDomainSpec* (*DmPolicyGetDomainSpecs)();


/**
Defines the function type for a static function that is implemented by
a device's domain policy DLL at ordinal 2. The domain manager uses this 
function to release the domain hierarchy specification returned by ordinal 1.
The implementation must never panic or leave in any way.

@see DmPolicy
*/
typedef void (*DmPolicyRelease) (const TDmDomainSpec* aDomainSpec);


/**
Defines the function type for a static function that is implemented by
a device's domain policy DLL at ordinal 3. The domain manager uses this 
function to access the hierarchy's policy.
The implementation may return a system-wide error code if it encounters an
error. This will abort policy loading and hierarchy creation. 
The implementation must never panic or leave in any way.

@see DmPolicy
*/
typedef TInt (*DmPolicyGetPolicy) (TDmHierarchyPolicy& aPolicy);


/**
Defines the function type for a static function that is implemented by
a device's domain policy DLL at ordinal 4. The domain manager uses this
function to obtain the state specification to configure the client transition
monitoring feature. 
This method is new in V2 of the domain policy and should not be present in 
V1 policy library.
The implementation must never panic or leave in any way.

The implementation returns either an error or the version of the state 
specification structure used in the array pointed to by aPtr on exit. 
When the return value is >=1, aNumElements must be >0.
Where a state specification is not required (i.e. client transition monitoring 
is not required) the implementation returns 0. When an error occurs a negative
system-wide error code is returned. In both these cases the output parameters are
ignored.

@see SDmStateSpecV1
@see DmPolicy
*/
typedef TInt (*DmPolicyGetStateSpec) (TAny*& aPtr, TUint& aNumElements);

/**
Defines the function type for a static function that is implemented by
a device's domain policy DLL at ordinal 5. The domain manager uses this 
function to release the state specification returned by ordinal 4. The 
implementation may be empty and simply return if no release action needs 
to be taken.

This method is new in V2 of the domain policy and should not be present in 
V1 policy library.
The implementation must never panic or leave in any way.

@see DmPolicy
*/
typedef void (*DmPolicyReleaseStateSpec) (TAny* aStateSpec);



/**
A set of static functions implemented in a domain hierarchy policy DLL that
the domain manager uses to access and release the domain hierarchy and 
domain state specifications.

@see DmPolicyOrdinals
*/
class DmPolicy
	{
public:
	// Original policy version methods
	IMPORT_C static const TDmDomainSpec* GetDomainSpecs();
	IMPORT_C static void Release(const TDmDomainSpec* aDomainSpec);
	IMPORT_C static TInt GetPolicy(TDmHierarchyPolicy& aPolicy);
	
	// Version 2 methods
	IMPORT_C static TInt GetStateSpec(TAny*& aPtr, TUint& aNumElements);
	IMPORT_C static void ReleaseStateSpec(TAny* aStateSpec);
	};



/**
Describes the purpose (and thus each function prototype) of each ordinal in the
policy DLL. There are two versions of this DLL in use:
- V1 DLLs implement ordinals 1..3
- V2 DLLs implement ordinals 1..5 

@see DmPolicy 
*/
enum DmPolicyOrdinals
	{
	// Policy DLL version 1 ordinals 
	EDmPolicyGetDomainSpecs = 1,
	EDmPolicyRelease,
	EDmPolicyGetPolicy,
	
	// Policy DLL version 2 ordinals for the "Transition Monitoring" feature.
	// These entry points are not needed in V1 policy libraries.
	EDmPolicyGetStateSpec,
	EDmPolicyReleaseStateSpec			
	};



#endif