diff -r 2b433474f2ba -r 957c583b417b userlibandfileserver/domainmgr/inc/domainpolicy.h --- 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 - - /** -@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