Function

IOPMAssertionCreateWithProperties

Creates an IOPMAssertion with more flexibility than IOPMAssertionCreateWithDescription.

Declaration

IOReturn IOPMAssertionCreateWithProperties(CFDictionaryRef AssertionProperties, IOPMAssertionID *AssertionID);

Parameters

AssertionProperties

Dictionary providing the properties of the assertion that need to be created.

AssertionID

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

Discussion

Create a new PM assertion - the caller must specify the type of assertion, initial level, and its properties as IOPMAssertionDictionaryKeys keys in the AssertionProperties dictionary. The following keys are recommend and/or required to be specified in the AssertionProperties dictionary argument.

  • REQUIRED: kIOPMAssertionTypeKey define the assertion type.

  • REQUIRED: kIOPMAssertionValueKey define an inital value.

  • REQUIRED: kIOPMAssertionNameKey Caller must describe the name for the activity that requires the change in behavior provided by the assertion.

  • OPTIONAL: kIOPMAssertionDetailsKey Caller may describe context-specific data about the assertion.

  • OPTIONAL: kIOPMAssertionHumanReadableReasonKey Caller may describe the reason for creating the assertion in a localizable CFString. This should be a human readable phrase that describes the actions the calling process is taking while the assertion is held, like "Downloading TV episodes", or "Compiling Projects"

  • OPTIONAL: kIOPMAssertionLocalizationBundlePathKey Caller may provide its bundle's path, where macOS can localize for GUI display the CFString specified by kIOPMAssertionHumanReadableReasonKey.

  • OPTIONAL: kIOPMAssertionPlugInIDKey if the caller is a plugin with a different identity than the process it's loaded in.

  • OPTIONAL: kIOPMAssertionFrameworkIDKey if the caller is a framework acting on behalf of a process.

  • OPTIONAL: The caller may specify a timeout.

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.

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