|
1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __SSMSTATEPOLICY_H__ |
|
17 #define __SSMSTATEPOLICY_H__ |
|
18 |
|
19 #include <e32def.h> |
|
20 #include <e32cmn.h> |
|
21 |
|
22 class CSsmCommandList; |
|
23 class TSsmState; |
|
24 class TSsmStateTransition; |
|
25 |
|
26 /** |
|
27 The UID value for System State Policy DLLs. |
|
28 @publishedPartner |
|
29 @released |
|
30 */ |
|
31 const TInt KSsmStatePolicyDllTypeUidValue=0x2000D75D; |
|
32 |
|
33 /** |
|
34 The UID for System State Policy DLLs. |
|
35 @publishedPartner |
|
36 @released |
|
37 */ |
|
38 const TUid KSsmStatePolicyDllTypeUid={KSsmStatePolicyDllTypeUidValue}; |
|
39 |
|
40 /** |
|
41 Filenames of System State Policy DLLs must be named on the pattern |
|
42 KSsmStatePolicyFilenamePrefix + TSsmState::MainState() + KSsmStatePolicyFilenamePostfix. |
|
43 The State must be formatted as a right-aligned hexadecimal number with the fixed width of 4 digits. |
|
44 These DLLs can only be loaded from the ROM file system (from Z:). |
|
45 @publishedPartner |
|
46 @released |
|
47 */ |
|
48 _LIT(KSsmStatePolicyFilenamePrefix, "ssm.state.policy."); |
|
49 |
|
50 /** |
|
51 @see KSsmStatePolicyFilenamePrefix |
|
52 @publishedPartner |
|
53 @released |
|
54 */ |
|
55 _LIT(KSsmStatePolicyFilenamePostfix, ".dll"); |
|
56 |
|
57 /** |
|
58 The protocol for System State Policy DLLs. |
|
59 These are not ECOM DLLs because they need to work before the ECOM server is started. |
|
60 |
|
61 The first function in System State Policy DLLs must have an exported function with |
|
62 following signature that returns an instance of the @c MSsmStatePolicy implementation: |
|
63 |
|
64 @code |
|
65 IMPORT_C static MSsmStatePolicy* NewL(); |
|
66 @endcode |
|
67 |
|
68 @publishedPartner |
|
69 @released |
|
70 */ |
|
71 class MSsmStatePolicy |
|
72 { |
|
73 public: |
|
74 |
|
75 enum TResponse |
|
76 { |
|
77 /* The requested system state is not possible to reach from current system state */ |
|
78 ENotAllowed, |
|
79 |
|
80 /* No state transition is currently ongoing */ |
|
81 EDefinitelyAllowed, |
|
82 |
|
83 /* The requested transition has higher priority than the currently queued transition, |
|
84 discard the queued transition and put the new request into the queue. Its up to the |
|
85 policy implementation to decide if the new request will cause the current transition |
|
86 to finish earlier than previously planned. */ |
|
87 ECurrentRemainReplaceQueued, |
|
88 |
|
89 /* The requested transition must action immediately, e.g. phone failure. Cancel the |
|
90 currently ongoing transition and immediately start executing this new transition request.*/ |
|
91 EReplaceCurrentClearQueue |
|
92 }; |
|
93 |
|
94 /** |
|
95 This function is guaranteed to be called before this System State Policy is used. |
|
96 It is intended for e.g. opening resource files or if you need to initialize |
|
97 hardware or talk to a domestic OS. |
|
98 @code |
|
99 //minimal implemementation of this function would be |
|
100 TRequestStatus* status = &aStatus; |
|
101 User::RequestComplete(status, KErrNone); |
|
102 @endcode |
|
103 @param aStatus to complete when the initialization operation has finished |
|
104 */ |
|
105 virtual void Initialize(TRequestStatus& aStatus) = 0; |
|
106 |
|
107 /** |
|
108 Used to inform the policy DLL to Cancel an asynchronous Initialize operation. |
|
109 */ |
|
110 virtual void InitializeCancel() = 0; |
|
111 |
|
112 /** |
|
113 Used to determine if an incoming request should be accepted or rejected. |
|
114 @param aRequest Contains information about the new request |
|
115 @param aCurrent Contains NULL or the first accepted but not yet completed transition request |
|
116 @param aQueued Contains NULL or a second accepted but not yet started transition request |
|
117 @param aMessage Contains information about the requesting client process. DLLs should not call RMessagePtr2::Complete. |
|
118 @return The decision from the the virtual implementation |
|
119 */ |
|
120 virtual TResponse TransitionAllowed(const TSsmStateTransition& aRequest, TSsmStateTransition const* aCurrent, TSsmStateTransition const* aQueued, const RMessagePtr2& aMessage) = 0; |
|
121 |
|
122 /** |
|
123 Used to create the command list associated with a sub state transition. |
|
124 @param aState Contains the state that identifies the command list to create |
|
125 @param aReason Contains the reason as given by the request |
|
126 @param aStatus to complete when the operation has finished |
|
127 */ |
|
128 virtual void PrepareCommandList(TSsmState aState, TInt aReason, TRequestStatus& aStatus) = 0; |
|
129 |
|
130 /** |
|
131 Used to inform the policy DLL that the pending asynchronous PrepareCommandList operation |
|
132 needs to be cancelled. |
|
133 */ |
|
134 virtual void PrepareCommandListCancel() = 0; |
|
135 |
|
136 /** |
|
137 Used to retrieve the command list once the PrepareCommandList has completed. |
|
138 Ownership of the returned command list is transferred to the caller. |
|
139 @return The command list created during the preceding PrepareCommandList step |
|
140 */ |
|
141 virtual CSsmCommandList* CommandList() = 0; |
|
142 |
|
143 /** |
|
144 Used to determine the next sub state transition. |
|
145 @param aCurrentTransition Contains the last executed state transition. |
|
146 @param aReason Contains the reason as given by the request |
|
147 @param aError Contains the completion code from the last executed sub-state transition |
|
148 @param aSeverity Contains the severity of the failed command in case the sub-state transition ended with an error |
|
149 @param aNextState The next System State to head for, if there is one |
|
150 @return ETrue if aNextState contains another System State to head for, or |
|
151 EFalse if there is no further transitions to do. |
|
152 */ |
|
153 virtual TBool GetNextState(TSsmState aCurrentTransition, TInt aReason, TInt aError, TInt aSeverity, TSsmState& aNextState) = 0; |
|
154 |
|
155 /** |
|
156 It is expected that Release will usually just call "delete this" on the object, |
|
157 but this will depend on the implementation of each policy. |
|
158 */ |
|
159 virtual void Release() = 0; |
|
160 |
|
161 private: |
|
162 //for future use, do not override these |
|
163 virtual void MSsmStatePolicy_Reserved_1() {} |
|
164 virtual void MSsmStatePolicy_Reserved_2() {} |
|
165 virtual void MSsmStatePolicy_Reserved_3() {} |
|
166 }; |
|
167 |
|
168 #endif |