--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/sysstatemgmt/systemstatemgr/inc/ssmstatepolicy.h Tue Feb 02 00:53:00 2010 +0200
@@ -0,0 +1,168 @@
+// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "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:
+//
+
+#ifndef __SSMSTATEPOLICY_H__
+#define __SSMSTATEPOLICY_H__
+
+#include <e32def.h>
+#include <e32cmn.h>
+
+class CSsmCommandList;
+class TSsmState;
+class TSsmStateTransition;
+
+/**
+ The UID value for System State Policy DLLs.
+ @publishedPartner
+ @released
+ */
+const TInt KSsmStatePolicyDllTypeUidValue=0x2000D75D;
+
+/**
+ The UID for System State Policy DLLs.
+ @publishedPartner
+ @released
+ */
+const TUid KSsmStatePolicyDllTypeUid={KSsmStatePolicyDllTypeUidValue};
+
+/**
+Filenames of System State Policy DLLs must be named on the pattern
+KSsmStatePolicyFilenamePrefix + TSsmState::MainState() + KSsmStatePolicyFilenamePostfix.
+The State must be formatted as a right-aligned hexadecimal number with the fixed width of 4 digits.
+These DLLs can only be loaded from the ROM file system (from Z:).
+@publishedPartner
+@released
+*/
+_LIT(KSsmStatePolicyFilenamePrefix, "ssm.state.policy.");
+
+/**
+@see KSsmStatePolicyFilenamePrefix
+@publishedPartner
+@released
+*/
+_LIT(KSsmStatePolicyFilenamePostfix, ".dll");
+
+/**
+The protocol for System State Policy DLLs.
+These are not ECOM DLLs because they need to work before the ECOM server is started.
+
+The first function in System State Policy DLLs must have an exported function with
+following signature that returns an instance of the @c MSsmStatePolicy implementation:
+
+@code
+IMPORT_C static MSsmStatePolicy* NewL();
+@endcode
+
+@publishedPartner
+@released
+*/
+class MSsmStatePolicy
+ {
+public:
+
+ enum TResponse
+ {
+ /* The requested system state is not possible to reach from current system state */
+ ENotAllowed,
+
+ /* No state transition is currently ongoing */
+ EDefinitelyAllowed,
+
+ /* The requested transition has higher priority than the currently queued transition,
+ discard the queued transition and put the new request into the queue. Its up to the
+ policy implementation to decide if the new request will cause the current transition
+ to finish earlier than previously planned. */
+ ECurrentRemainReplaceQueued,
+
+ /* The requested transition must action immediately, e.g. phone failure. Cancel the
+ currently ongoing transition and immediately start executing this new transition request.*/
+ EReplaceCurrentClearQueue
+ };
+
+ /**
+ This function is guaranteed to be called before this System State Policy is used.
+ It is intended for e.g. opening resource files or if you need to initialize
+ hardware or talk to a domestic OS.
+ @code
+ //minimal implemementation of this function would be
+ TRequestStatus* status = &aStatus;
+ User::RequestComplete(status, KErrNone);
+ @endcode
+ @param aStatus to complete when the initialization operation has finished
+ */
+ virtual void Initialize(TRequestStatus& aStatus) = 0;
+
+ /**
+ Used to inform the policy DLL to Cancel an asynchronous Initialize operation.
+ */
+ virtual void InitializeCancel() = 0;
+
+ /**
+ Used to determine if an incoming request should be accepted or rejected.
+ @param aRequest Contains information about the new request
+ @param aCurrent Contains NULL or the first accepted but not yet completed transition request
+ @param aQueued Contains NULL or a second accepted but not yet started transition request
+ @param aMessage Contains information about the requesting client process. DLLs should not call RMessagePtr2::Complete.
+ @return The decision from the the virtual implementation
+ */
+ virtual TResponse TransitionAllowed(const TSsmStateTransition& aRequest, TSsmStateTransition const* aCurrent, TSsmStateTransition const* aQueued, const RMessagePtr2& aMessage) = 0;
+
+ /**
+ Used to create the command list associated with a sub state transition.
+ @param aState Contains the state that identifies the command list to create
+ @param aReason Contains the reason as given by the request
+ @param aStatus to complete when the operation has finished
+ */
+ virtual void PrepareCommandList(TSsmState aState, TInt aReason, TRequestStatus& aStatus) = 0;
+
+ /**
+ Used to inform the policy DLL that the pending asynchronous PrepareCommandList operation
+ needs to be cancelled.
+ */
+ virtual void PrepareCommandListCancel() = 0;
+
+ /**
+ Used to retrieve the command list once the PrepareCommandList has completed.
+ Ownership of the returned command list is transferred to the caller.
+ @return The command list created during the preceding PrepareCommandList step
+ */
+ virtual CSsmCommandList* CommandList() = 0;
+
+ /**
+ Used to determine the next sub state transition.
+ @param aCurrentTransition Contains the last executed state transition.
+ @param aReason Contains the reason as given by the request
+ @param aError Contains the completion code from the last executed sub-state transition
+ @param aSeverity Contains the severity of the failed command in case the sub-state transition ended with an error
+ @param aNextState The next System State to head for, if there is one
+ @return ETrue if aNextState contains another System State to head for, or
+ EFalse if there is no further transitions to do.
+ */
+ virtual TBool GetNextState(TSsmState aCurrentTransition, TInt aReason, TInt aError, TInt aSeverity, TSsmState& aNextState) = 0;
+
+ /**
+ It is expected that Release will usually just call "delete this" on the object,
+ but this will depend on the implementation of each policy.
+ */
+ virtual void Release() = 0;
+
+private:
+ //for future use, do not override these
+ virtual void MSsmStatePolicy_Reserved_1() {}
+ virtual void MSsmStatePolicy_Reserved_2() {}
+ virtual void MSsmStatePolicy_Reserved_3() {}
+ };
+
+#endif