Hardware Dev Center

Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

PowerSetRequest function

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

Syntax


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.

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 systems capable of connected standby. 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.

On systems not capable of connected standby, an active PowerRequestExecutionRequired request implies PowerRequestSystemRequired.

Note  PowerRequestExecutionRequired is supported starting with Windows 8 and Windows Server 2012.

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 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

PowerClearRequest
PowerCreateRequest

 

 

Community Additions

Show:
© 2015 Microsoft