Home Library Learn Downloads Support Community
Sign in | United States - English | |
This topic has not yet been rated - Rate this topic

PowerSetRequest function

Applies to: desktop apps only

Increments the count of power requests of the specified type for a power request object.

Syntax

Copy 
BOOL PowerSetRequest(
  __in  HANDLE PowerRequest,
  __in  POWER_REQUEST_TYPE RequestType
);

Parameters

PowerRequest [in]

A handle to a power request object.

RequestType [in]

The power request type to be incremented. This parameter can be one of the following values.

ValueMeaning
PowerRequestDisplayRequired

The display remains on even if there is no user input for an extended period of time.

PowerRequestSystemRequired

The system continues to run instead of entering sleep after a period of user inactivity.

This request type is not honored on AOAC-capable systems. Applications should use PowerRequestExecutionRequired requests instead.

PowerRequestAwayModeRequired

The system enters away mode instead of sleep in response to explicit action by the user. In away mode, the system continues to run but turns off audio and video to give the appearance of sleep.

PowerRequestExecutionRequired

The calling process continues to run instead of being suspended or terminated by process lifetime management mechanisms. When and how long the process is allowed to run depends on the operating system and power policy settings.

When a PowerRequestExecutionRequired request is active, it implies PowerRequestSystemRequired.

The PowerRequestExecutionRequired request type can be used only by applications. Services cannot use this request type.

Windows 7 and Windows Server 2008 R2:  This request type is supported starting with Windows 8 and Windows Server 8 Beta.

 

Return value

If the function succeeds, it returns a nonzero value.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

To conserve power and provide the best user experience, applications that use power requests should follow these best practices:

  • When creating a power request, provide a localized text string that describes the reason for the request in the REASON_CONTEXT structure.
  • Call PowerSetRequest immediately before the scenario that requires the request.
  • Call PowerClearRequest to decrement the reference count for the request as soon as the scenario is finished.
  • Clean up all request objects and associated handles before the process exits or the service stops.

Requirements

Minimum supported client

Windows 7

Minimum supported server

Windows Server 2008 R2

Header
Winbase.h (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

See also

PowerClearRequest
PowerCreateRequest

 

 

Send comments about this topic to Microsoft

Build date: 2/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Documentation Clarification
Hey, I'm working with this API as well and saw your complaints, and wanted to help answer your questions. 1) PowerRequestExecutionRequired is new to windows 8, as the documentation states that this is available starting in Windows Developer Preview. Consequently, only Visual Studio 2011 Developer Preview running on Windows Developer Preview would pick this up. 2) Regarding how PowerCreateRequest works, I find the documentation for that function (linked from this page) and the description of REASON_CONTEXT (linked from the PowerCreateRequest page) to be adequate enough for my application - are there more specific questions that aren't addressed?
History
Documentation Clarification
Hey, I'm working with this API as well and saw your complaints, and wanted to help answer your questions. 1) PowerRequestExecutionRequired is new to windows 8, as the documentation states that this is available starting in Windows Developer Preview. Consequently, only Visual Studio 2011 Developer Preview running on Windows Developer Preview would pick this up. 2) Regarding how PowerCreateRequest works, I find the documentation for that function (linked from this page) and the description of REASON_CONTEXT (linked from the PowerCreateRequest page) to be adequate enough for my application - are there more specific questions that aren't addressed?
History
This documentation isn't very helpful
As someone who is trying to perform programmatic system and/or monitor power state manipulation on Windows Vista and 7, I find the documentation on the whole topic to be very muddled, contradictory and incomplete. Why isn't PowerRequestExecutionRequired defined in any header files? How does PowerCreateRequest work and what should be passed in the REASON_CONTEXT structure? What is the definitive way to put a monitor into powersave mode? etc, etc, etc.
History
Inconsistencies yet again
This page is the only one that mentions "PowerRequestExecutionRequired" What happened to it ? POWER_REQUEST_TYPE enumeration http://msdn.microsoft.com/en-us/library/windows/desktop/dd405534(v=vs.85).aspx Doesn't mention it at all. Visual studio 2010 sp1 doesn't define it. Was it removed in the last minute ?
History