Mercurial Mercurial > oss > FCL > sf > os > kernelhwsrv / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
userlibandfileserver/domainmgr/inc/domainpolicy.h
changeset 279 957c583b417b
parent 0 a41df078684a 
--- a/userlibandfileserver/domainmgr/inc/domainpolicy.h	Tue Sep 28 15:28:31 2010 +0100
+++ b/userlibandfileserver/domainmgr/inc/domainpolicy.h	Mon Oct 04 12:03:52 2010 +0100
@@ -1,4 +1,4 @@
-// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
+// 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"
@@ -11,6 +11,15 @@
 // 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
@@ -25,153 +34,232 @@
 #include <domaindefs.h>
 
 
-
-
 /**
-@publishedPartner
-@released
-
 Defines the characteristics of a domain.
 */
 struct TDmDomainSpec
 	{
-	/**
-	The domain identifier.
-	*/
+	/**	The 16-bit domain identifier */
 	TDmDomainId					iId;
 	
-	/**
-	The domain identifier of the domain's parent.
-	*/
+	/**	The domain identifier of the domain's parent */
 	TDmDomainId					iParentId;
 
-	/**
-	The security capability required to join this domain
-	*/
+	/**	The security capability required to join this domain */
 	TStaticSecurityPolicy		iJoinPolicy;
 	
-	/**
-	The initial state of the domain after construction.
-	*/
+	/**	The initial state of the domain after construction */
 	TDmDomainState				iInitState;
 	
-	/**
-	The total time allowed for members of the domain to acknowledge
-	a transition.
-	*/
+	/**	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}
 
 
 
 /**
-@internalAll
+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. 
 
-The possible ways in which the domain manager can behave
-when a transition fails.
-
-This is defined for each domain hierarchy.
-
-@see TDmHierarchyPolicy
+@see TDmTransitionFailurePolicy
 */
-enum TDmTransitionFailurePolicy
+class TDmHierarchyPolicy
 	{
-	/**
-	The domain manager stops at the first transition failure.
-	*/
-	ETransitionFailureStop,
-
-	/**
-	The domain manager continues at any transition failure.
-	*/
-	ETransitionFailureContinue
+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;
 	};
 
 
 
 /**
-@internalTechnology
+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
 
-Defines the policy for a particular domain hierarchy.
+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()
 */
-class TDmHierarchyPolicy
+struct SDmStateSpecV1
 	{
-public:
-	/**
-	direction of traverse if target state is after current state
-	*/
-	TDmTraverseDirection iPositiveTransitions;
-	/**
-	direction of traverse if target state is before current state
-	*/
-	TDmTraverseDirection iNegativeTransitions;
-	/**
-	policy which outlines the action upon transition failure
-	*/
-	TDmTransitionFailurePolicy iFailurePolicy;
+	/**	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;
+
 
 
 /**
-@internalAll
+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
 
-Defines the function type for a static function that is implemented by
-a device's domain policy DLL.
+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.
 
-The domain manager uses this function to access the hierarchy's policy.
+@see DmPolicy
 */
 typedef const TDmDomainSpec* (*DmPolicyGetDomainSpecs)();
 
 
 /**
-@internalAll
+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.
 
-Defines the function type for a static function that is implemented by
-a device's domain policy DLL.
-
-The domain manager uses this function to release the domain
-hierarchy specification.
+@see DmPolicy
 */
 typedef void (*DmPolicyRelease) (const TDmDomainSpec* aDomainSpec);
 
 
 /**
-@internalAll
+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.
 
-Defines the function type for a static function that is implemented by
-a device's domain policy DLL.
-
-The domain manager uses this function to access the domain
-hierarchy specification.
+@see DmPolicy
 */
 typedef TInt (*DmPolicyGetPolicy) (TDmHierarchyPolicy& aPolicy);
 
+
 /**
-@publishedPartner
-@released
+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);
 
-A set of static functions implemented by a device's domain policy DLL that
-the domain manager uses to access, and release, the domain
-hierarchy specification.
+/**
+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);
 	};
 
 
+
 /**
-@internalTechnology
+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
+	EDmPolicyGetPolicy,
+	
+	// Policy DLL version 2 ordinals for the "Transition Monitoring" feature.
+	// These entry points are not needed in V1 policy libraries.
+	EDmPolicyGetStateSpec,
+	EDmPolicyReleaseStateSpec			
 	};
 
+
+
 #endif
FCL/sf/os/kernelhwsrv