Function

IOPMAssertionCreateWithDescription

Declaration

IOReturn IOPMAssertionCreateWithDescription(CFStringRef AssertionType, CFStringRef Name, CFStringRef Details, CFStringRef HumanReadableReason, CFStringRef LocalizationBundlePath, CFTimeInterval Timeout, CFStringRef TimeoutAction, IOPMAssertionID *AssertionID);

Parameters

AssertionType

An assertion type constant. Caller must specify this argument.

Name

A CFString value to correspond to key kIOPMAssertionNameKey. Caller must specify this argument.

Details

A CFString value to correspond to key kIOPMAssertionDetailsKey. Caller my pass NULL, but it helps power users and administrators identify the reasons for this assertion.

HumanReadableReason

A CFString value to correspond to key kIOPMAssertionHumanReadableReasonKey. Caller may pass NULL, but if it's specified macOS may display it to users to describe the active assertions on their system.

LocalizationBundlePath

A CFString value to correspond to key kIOPMAssertionLocalizationBundlePathKey. This bundle path should include a localization for the string HumanReadableReason Caller may pass NULL, but this argument is required if caller specifies HumanReadableReason

Timeout

Specifies a timeout for this assertion. Pass 0 for no timeout.

TimeoutAction

Specifies a timeout action. Caller my pass NULL. If a timeout is specified but a TimeoutAction is not, the default timeout action is kIOPMAssertionTimeoutActionTurnOff

AssertionID

(Output) On successful return, contains a unique reference to a PM assertion.

Return Value

kIOReturnSuccess, or another IOKit return code on error.

Discussion

Creates an IOPMAssertion. This is the preferred API to call to create an assertion. It allows the caller to specify the Name, Details, and HumanReadableReason at creation time. There are other keys that can further describe an assertion, but most developers don't need to use them. Use IOPMAssertionSetProperties or IOPMAssertionCreateWithProperties if you need to specify properties that aren't available here.

See Also

Assertions

IOPMAssertionCopyProperties

Copies details about an IOPMAssertion

IOPMAssertionCreate

Dynamically requests a system behavior from the power management system.

Deprecated
IOPMAssertionCreateWithName

Dynamically requests a system behavior from the power management system.

IOPMAssertionCreateWithProperties

Creates an IOPMAssertion with more flexibility than IOPMAssertionCreateWithDescription.

IOPMAssertionDeclareUserActivity

Declares that the user is active on the system. This causes the display to power on and postpone display sleep up to the user's display sleep Energy Saver settings. If you prefer to hold the display awake for a longer period and you know how long you'd like to hold it, consider taking assertion kIOPMAssertionTypePreventUserIdleDisplaySleep using IOPMAssertionCreateWithDescription API instead.

IOPMAssertionRelease

Decrements the assertion's retain count.

IOPMAssertionRetain

Increments the assertion's retain count.

IOPMAssertionSetProperty

Sets a property in the assertion.

IOPMCopyAssertionsByProcess

Returns a dictionary listing all assertions, grouped by their owning process.

IOPMCopyAssertionsStatus

Returns a list of available assertions and their system-wide levels.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software