diff -r 000000000000 -r 4e1aa6a622a0 sysstatemgmt/systemstatemgr/inc/ssmstatepolicy.h --- /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 +#include + +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