1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

     1 // Copyright (c) 2002-2010 Nokia Corporation and/or its subsidiary(-ies).

    28 

    37 /**

    29 

    30 /**

    31 @publishedPartner

    32 @released

    33 

    38 	/**

    42 	/**	The 16-bit domain identifier */

    39 	The domain identifier.

    40 	*/

    43 	/**

    45 	/**	The domain identifier of the domain's parent */

    44 	The domain identifier of the domain's parent.

    45 	*/

    48 	/**

    48 	/**	The security capability required to join this domain */

    49 	The security capability required to join this domain

    50 	*/

    53 	/**

    51 	/**	The initial state of the domain after construction */

    54 	The initial state of the domain after construction.

    55 	*/

    58 	/**

    54 	/**	The total time allowed for the domain to complete a state transition.

    59 	The total time allowed for members of the domain to acknowledge

    55 	Members of the domain must acknowledge a transition within this time.

    60 	a transition.

    56 	Measured in microseconds. */

    61 	*/

    65 

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

    66 

    61 

    67 

    62 

    68 /**

    63 

    69 @internalAll

    64 /**

    70 

    65 Defines the overall traversal and failure policy for a particular 

    71 The possible ways in which the domain manager can behave

    66 domain hierarchy and is returned by DmPolicy::GetPolicy().

    72 when a transition fails.

    67 Note the failure policy can be overridden for individual 

    73 

    68 states in V2 policies. 

    74 This is defined for each domain hierarchy.

    69 

    75 

    70 @see TDmTransitionFailurePolicy

    76 @see TDmHierarchyPolicy

    77 */

    78 enum TDmTransitionFailurePolicy

    79 	{

    80 	/**

    81 	The domain manager stops at the first transition failure.

    82 	*/

    83 	ETransitionFailureStop,

    84 

    85 	/**

    86 	The domain manager continues at any transition failure.

    87 	*/

    88 	ETransitionFailureContinue

    89 	};

    90 

    91 

    92 

    93 /**

    94 @internalTechnology

    95 

    96 Defines the policy for a particular domain hierarchy.

   101 	/**

    75 	/** Direction of traversal if target state is after current state */

   102 	direction of traverse if target state is after current state

   103 	*/

   105 	/**

    77 	

   106 	direction of traverse if target state is before current state

    78 	/**	Direction of traversal if target state is before current state */

   107 	*/

   109 	/**

    80 	

   110 	policy which outlines the action upon transition failure

    81 	/** Policy which outlines the action upon transition failure */

   111 	*/

   116 /**

    86 

   117 @internalAll

    87 /**

   118 

    88 Defines the characteristics of a state and is used by entry points introduced

   119 Defines the function type for a static function that is implemented by

    89 in version 2 of the policy API. The structure itself is also versioned with V1 

   120 a device's domain policy DLL.

    90 in use with version 2 policy libraries. 

   121 

    91 

   122 The domain manager uses this function to access the hierarchy's policy.

    92 Policy providers provide an object of this type for each state they want to:

    93 - enable the Transition Monitoring feature or/and

    94 - override the default failure policy

    95 

    96 Enabling transition monitoring will allow trusted clients to receive more time

    97 to complete their work before final acknowledgment. Enable transition 

    98 monitoring to ensure a fair completion of the transition e.g. shutdown system.

    99 Where transition monitoring is enabled the Domain level timer is not used

   100 and iTimeBudgetUs provided in TDmDomainSpec is ignored.

   101 

   102 The global failure policy is returned by DmPolicy::GetPolicy() and in V1 

   103 policies this applies to all state transitions. iFailurePolicy in this 

   104 structure allows different failure policies for different state transitions. 

   105 

   106 @see DmPolicy::GetStateSpec()

   107 */

   108 struct SDmStateSpecV1

   109 	{

   110 	/**	The destination state of the transition */

   111 	TDmDomainState		iState;

   112 	

   113 	/** Transition Monitoring: member transition timeout granularity, in 

   114 	milliseconds, e.g. 200ms. Set to 0 to not use transition monitoring for 

   115 	this state. */

   116 	TInt16				iTimeoutMs;	

   117 		

   118 	/** Transition Monitoring: maximum number of times a domain member may be 

   119 	granted an additional timeout period. Set to 0 when transition 

   120 	monitoring not used for this state. */	

   121 	TInt16				iDeferralLimit;	

   122 	

   123 	/** Specifies the failure policy for transitions to the target state, see

   124 	TDmTransitionFailurePolicy. Overrides the global value returned by 

   125 	the policy function DmPolicyGetPolicy(). 

   126 	Set to ETransitionFailureUsePolicyFromOrdinal3 if override not required. */	

   127 	TInt16			    iFailurePolicy;

   128 	};

   129 	

   130 const TInt KSDmStateSpecV1 = 1;

   131 

   132 

   133 

   134 /**

   135 Defines the function type for a static function that is implemented by

   136 a device's domain policy DLL at ordinal 1.

   137 The domain manager uses this function to access the domain

   138 hierarchy specification. The pointer returned must point to an array of

   139 TDmDomainSpec objects where the last object in the array is defined

   140 using the END macro, as shown below.

   141 @code

   142 	. . .

   143 	TDM_DOMAIN_SPEC_END

   144 	};

   145 @endcode

   146 

   147 The implementation should return NULL if it is unable to supply the requested

   148 information due to an error. This will abort policy loading and hierarchy 

   149 creation. 

   150 The implementation must never panic or leave in any way.

   151 

   152 @see DmPolicy

   128 @internalAll

   158 Defines the function type for a static function that is implemented by

   129 

   159 a device's domain policy DLL at ordinal 2. The domain manager uses this 

   130 Defines the function type for a static function that is implemented by

   160 function to release the domain hierarchy specification returned by ordinal 1.

   131 a device's domain policy DLL.

   161 The implementation must never panic or leave in any way.

   132 

   162 

   133 The domain manager uses this function to release the domain

   163 @see DmPolicy

   134 hierarchy specification.

   140 @internalAll

   169 Defines the function type for a static function that is implemented by

   141 

   170 a device's domain policy DLL at ordinal 3. The domain manager uses this 

   142 Defines the function type for a static function that is implemented by

   171 function to access the hierarchy's policy.

   143 a device's domain policy DLL.

   172 The implementation may return a system-wide error code if it encounters an

   144 

   173 error. This will abort policy loading and hierarchy creation. 

   145 The domain manager uses this function to access the domain

   174 The implementation must never panic or leave in any way.

   146 hierarchy specification.

   175 

   176 @see DmPolicy

   150 /**

   180 

   151 @publishedPartner

   181 /**

   152 @released

   182 Defines the function type for a static function that is implemented by

   153 

   183 a device's domain policy DLL at ordinal 4. The domain manager uses this

   154 A set of static functions implemented by a device's domain policy DLL that

   184 function to obtain the state specification to configure the client transition

   155 the domain manager uses to access, and release, the domain

   185 monitoring feature. 

   156 hierarchy specification.

   186 This method is new in V2 of the domain policy and should not be present in 

   187 V1 policy library.

   188 The implementation must never panic or leave in any way.

   189 

   190 The implementation returns either an error or the version of the state 

   191 specification structure used in the array pointed to by aPtr on exit. 

   192 When the return value is >=1, aNumElements must be >0.

   193 Where a state specification is not required (i.e. client transition monitoring 

   194 is not required) the implementation returns 0. When an error occurs a negative

   195 system-wide error code is returned. In both these cases the output parameters are

   196 ignored.

   197 

   198 @see SDmStateSpecV1

   199 @see DmPolicy

   200 */

   201 typedef TInt (*DmPolicyGetStateSpec) (TAny*& aPtr, TUint& aNumElements);

   202 

   203 /**

   204 Defines the function type for a static function that is implemented by

   205 a device's domain policy DLL at ordinal 5. The domain manager uses this 

   206 function to release the state specification returned by ordinal 4. The 

   207 implementation may be empty and simply return if no release action needs 

   208 to be taken.

   209 

   210 This method is new in V2 of the domain policy and should not be present in 

   211 V1 policy library.

   212 The implementation must never panic or leave in any way.

   213 

   214 @see DmPolicy

   215 */

   216 typedef void (*DmPolicyReleaseStateSpec) (TAny* aStateSpec);

   217 

   218 

   219 

   220 /**

   221 A set of static functions implemented in a domain hierarchy policy DLL that

   222 the domain manager uses to access and release the domain hierarchy and 

   223 domain state specifications.

   224 

   225 @see DmPolicyOrdinals

   164 	};

   234 	

   165 

   235 	// Version 2 methods

   166 

   236 	IMPORT_C static TInt GetStateSpec(TAny*& aPtr, TUint& aNumElements);

   167 /**

   237 	IMPORT_C static void ReleaseStateSpec(TAny* aStateSpec);

   168 @internalTechnology

   238 	};

   239 

   240 

   241 

   242 /**

   243 Describes the purpose (and thus each function prototype) of each ordinal in the

   244 policy DLL. There are two versions of this DLL in use:

   245 - V1 DLLs implement ordinals 1..3

   246 - V2 DLLs implement ordinals 1..5 

   247 

   248 @see DmPolicy 

   174 	EDmPolicyGetPolicy

   255 	EDmPolicyGetPolicy,

   175 	};

   256 	

   257 	// Policy DLL version 2 ordinals for the "Transition Monitoring" feature.

   258 	// These entry points are not needed in V1 policy libraries.

   259 	EDmPolicyGetStateSpec,

   260 	EDmPolicyReleaseStateSpec			

   261 	};

   262 

   263