Platforms to show: All Mac Windows Linux Cross-Platform

Back to IOPMAssertionMBS class.

IOPMAssertionMBS.AssertionsByProcess as Dictionary

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Returns a dictionary listing all assertions, grouped by their owning process.

Notes: One process may have multiple assertions. Several processes may have asserted the same assertion to different levels.

On success, this returns a dictionary of assertions per process. At the top level, keys to the Dictionary are pids stored as Integer. The value associated with each pid is an array of active assertions. Each entry in the array is an assertion represented as a Dictionary. See the keys kIOPMAssertionTypeKey and kIOPMAssertionLevelKey.

IOPMAssertionMBS.AssertionsStatus as Dictionary

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Returns a list of available assertions and their system-wide levels.

The system-wide level is the maximum of all individual assertions' levels.

On success, this returns a Dictionary of all assertions currently available.
The keys in the dictionary are the assertion types, and the value of each is a CFNumber that represents the aggregate level for that assertion.

IOPMAssertionMBS.CreateWithDescription(AssertionType as string, Name as string, Details as string = "", HumanReadableReason as string = "", LocalizationBundlePath as string = "", Timeout as Double = 0, TimeoutAction as string = "") as IOPMAssertionMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
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 SetProperty or CreateWithProperties if you need to specify properties that aren't available here.

AssertionType: An assertion type constant. Caller must specify this argument.
Name: A String value to correspond to key kIOPMAssertionNameKey. Caller must specify this argument.
Details: A String value to correspond to key kIOPMAssertionDetailsKey. Caller my pass "", but it helps power users and administrators identify the reasons for this assertion.
HumanReadableReason: A String value to correspond to key kIOPMAssertionHumanReadableReasonKey. Caller may pass "", but if it's specified OS X may display it to users to describe the active assertions on their system.
LocalizationBundlePath: A String value to correspond to key kIOPMAssertionLocalizationBundlePathKey. This bundle path should include a localization for the string HumanReadableReason. Caller may pass "", 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 "". If a timeout is specified but a TimeoutAction is not, the default timeout action is kIOPMAssertionTimeoutActionTurnOff.

On success this function returns a new assertion.

IOPMAssertionMBS.CreateWithHandle(Handle as Integer) as IOPMAssertionMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Creates a new object with retaining given handle.

IOPMAssertionMBS.CreateWithName(type as string, level as Integer, name as string) as IOPMAssertionMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Dynamically requests a system behavior from the power management system.

Create is deprecated in favor of CreateWithProperties. Please use that version of this API instead.

No special privileges are necessary to make this call - any process may activate a power assertion. Caller must specify an AssertionName - "" is not a valid input.

TypeThe String assertion type to request from the PM system.
LevelPass kIOPMAssertionLevelOn or kIOPMAssertionLevelOff.
NameA string that describes the name of the caller and the activity being handled by this assertion (e.g. "Mail Compacting Mailboxes"). Name may be no longer than 128 characters.

On success, returns an IOPMAssertionMBS object.

IOPMAssertionMBS.CreateWithProperties(AssertionProperties as Dictionary) as IOPMAssertionMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Creates an IOPMAssertion with more flexibility than CreateWithDescription.

AssertionProperties: Dictionary providing the properties of the assertion that need to be created.
On successful return, returns the assertion.

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 String. 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 OS X can localize for GUI display the String 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.

IOPMAssertionMBS.DeclareUserActivity(AssertionName as string, userType as Integer, byref AssertionID as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
shared method Power MBS MacOSX Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
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 CreateWithDescription instead.

No special privileges are necessary to make this call - any process may call this API. Caller must specify an AssertionName.

AssertionName: A string that describes the name of the caller and the activity being handled by this assertion (e.g. "Mail Compacting Mailboxes"). Name may be no longer than 128 characters.
userType: This parameter specifies if the active user is located locally in front of the system or connected to the system over the network. Various components of the system are maintained at different power levels depending on user location.

On Success, unique id will be returned in this parameter. Caller may call this function again with the unique id retured previously to report continous user activity. The unique id returned by this function may change on each call depending on how frequently this function call is repeated and the current display sleep timer value. If you make this call more than once, track the returned value for assertionID, and pass it in as an argument on each call.

Returns kIOReturnSuccess (0) on success, any other return indicates PM could not successfully activate the specified assertion.

The items on this page are in the following plugins: MBS MacOSX Plugin.


The biggest plugin in space...