sl@0: // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32\euser\us_power.cpp
sl@0: // 
sl@0: //
sl@0: 
sl@0: #include <e32power.h>
sl@0: #include "us_std.h"
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: /**
sl@0: Enables wakeup events.
sl@0: 
sl@0: Starts a system-wide transition to a low power state enabling wakeup events.
sl@0: 
sl@0: The exact specification of wakeup events depends on the target power state
sl@0: and the platform.
sl@0: For example, an absolute timer expiration event wakes up the system from
sl@0: the EPwStandby power state on all currently supported platforms.
sl@0: 
sl@0: If, at the time this function is called, wakeup events are enabled, then
sl@0: the implementation disables them before enabling them again.  
sl@0: 
sl@0: The caller must have PowerMgnt capability to perform this call; otherwise
sl@0: it panics with EPlatformSecurityTrap code.
sl@0: 
sl@0: @param aState   The target low power state; this can be EPwStandby or KPwOff.
sl@0: 				
sl@0: @return KErrNone, if successful,
sl@0:         KErrArgument, if aState is neither EPwStandby nor KPwOff;
sl@0:         otherwise one of the other system-wide error codes.
sl@0: 		
sl@0: @panic KERN-EXEC 46 if the caller does not have PowerMgnt capability.
sl@0: 		
sl@0: @see Power::DisableWakeupEvents()		
sl@0: 
sl@0: @capability PowerMgmt
sl@0: */
sl@0: EXPORT_C TInt Power::EnableWakeupEvents(TPowerState aState)
sl@0: 	{
sl@0: 	return Exec::PowerEnableWakeupEvents(aState);
sl@0: 	}
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: /**
sl@0: Disables wakeup events.
sl@0: 
sl@0: If, at the time this function is called, wakeup events are disabled, then
sl@0: the function does nothing and returns immediately.
sl@0: 
sl@0: The caller must have PowerMgnt capability to perform this call; otherwise it
sl@0: panics with EPlatformSecurityTrap code.
sl@0: 		
sl@0: @panic KERN-EXEC 46 if the caller does not have PowerMgnt capability.		
sl@0: 
sl@0: @capability PowerMgmt
sl@0: */
sl@0: EXPORT_C void Power::DisableWakeupEvents()
sl@0: 	{
sl@0: 	Exec::PowerDisableWakeupEvents();
sl@0: 	}
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: /**
sl@0: Requests notification of a subsequent wakeup event.
sl@0: 
sl@0: Typically the user-side domain manager issues this request 
sl@0: before starting a system-wide transition to a low power state by
sl@0: enabling wakeup events.
sl@0: 
sl@0: Only one pending request is allowed. The request completes immediately
sl@0: with KErrInUse status if another request is currently pending.
sl@0: 
sl@0: The caller must have PowerMgnt capability to perform this call; otherwise
sl@0: it panics with EPlatformSecurityTrap code.
sl@0: 
sl@0: @param aStatus The request status to signal on wakeup event
sl@0: 
sl@0: @panic KERN-EXEC 46 if the caller does not have PowerMgnt capability.
sl@0: 
sl@0: @see Power::EnableWakeupEvents()
sl@0: 
sl@0: @capability PowerMgmt
sl@0: */
sl@0: EXPORT_C void Power::RequestWakeupEventNotification(TRequestStatus& aStatus)
sl@0: 	{
sl@0: 	aStatus = KRequestPending;
sl@0: 	Exec::PowerRequestWakeupEventNotification(&aStatus);
sl@0: 	}
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: /**
sl@0: Cancels a pending wakeup event notification request.
sl@0: 
sl@0: If, at the time this function is called, the notification request is still
sl@0: pending, then the request completes with KErrCancel status.
sl@0: 
sl@0: The caller must have PowerMgnt capability to perform this call; otherwise it panics with
sl@0: EPlatformSecurityTrap code
sl@0: 
sl@0: @panic KERN-EXEC 46 if the caller does not have PowerMgnt capability.
sl@0: 
sl@0: @capability PowerMgmt
sl@0: */
sl@0: EXPORT_C void Power::CancelWakeupEventNotification()
sl@0: 	{
sl@0: 	Exec::PowerCancelWakeupEventNotification();
sl@0: 	}
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: /**
sl@0: Lowers the kernel power state.
sl@0: 	 
sl@0: Changes the kernel power state from EPwActive to the state specified by the last 
sl@0: call to EnableWakeupEvents().
sl@0: 
sl@0: If the target state is EPwStandby, the function returns either immediately,
sl@0: if at least one wakeup event has occurred since the last call
sl@0: to EnableWakeupEvent(), or when a wakeup event eventually occurs.
sl@0: 		
sl@0: When this function returns, wakeup events are disabled.
sl@0: 
sl@0: If the target state is EPwOff, this function never returns,
sl@0: the system is powered off, and can subsequently only come back by rebooting.
sl@0: 
sl@0: The caller must have PowerMgnt capability to perform this call; otherwise
sl@0: it panics with EPlatformSecurityTrap code
sl@0: 
sl@0: @return KErrNone, if successful;
sl@0:         KErrNotReady, if wakeup events are disabled at the time this function is called;
sl@0:         otherwise one of the other system-wide error codes.
sl@0: 
sl@0: @panic KERN-EXEC 46 if the caller does not have PowerMgnt capability.
sl@0: 
sl@0: @capability PowerMgmt
sl@0: */
sl@0: EXPORT_C TInt Power::PowerDown()
sl@0: 	{ 
sl@0: 	return Exec::PowerDown();
sl@0: 	}