IOPMLib.h

Overview

IOPMLib provides access to common power management facilites, like initiating system sleep, getting current idle timer values, registering for sleep/wake notifications, and preventing system sleep.

Assertions

Group members:

ScheduledEvents

Group members:

Notifications

Group members:

IOSystemLoadAdvisory

Group members:

Functions

IOAllowPowerChange

The caller acknowledges notification of a power state change on a device it has registered for notifications for via IORegisterForSystemPower or IORegisterApp.

IOCancelPowerChange

The caller denies an idle system sleep power state change.

IOCopySystemLoadAdvisoryDetailed

Indicates how user activity, battery level, and thermal level each contribute to the overall "SystemLoadAdvisory" level. In the future, this combined level may represent new levels as well.

IODeregisterApp

Disconnects the caller from an IOService after receiving power state change notifications from the IOService. (Caller must also release IORegisterApp's return io_connect_t and returned IONotificationPortRef for complete clean-up).

IODeregisterForSystemPower

Disconnects the caller from the Root Power Domain IOService after receiving system power state change notifications. (Caller must also destroy the IONotificationPortRef returned from IORegisterForSystemPower.)

IOGetSystemLoadAdvisory

Returns a hint about whether now would be a good time to perform time-insensitive work.

IOPMAssertionCreate

Dynamically requests a system behavior from the power management system.

IOPMAssertionCreateWithName

Dynamically requests a system behavior from the power management system.

IOPMAssertionRelease

Releases the behavior requested in IOPMAssertionCreate

IOPMCancelScheduledPowerEvent

Cancel a previously scheduled power event.

IOPMCopyAssertionsByProcess

Returns a dictionary mapping processes to the assertions they are holding active.

IOPMCopyAssertionsStatus

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

IOPMCopyBatteryInfo

Request raw battery data from the system.

IOPMCopyScheduledPowerEvents

List all scheduled system power events

IOPMFindPowerManagement

Finds the Root Power Domain IOService.

IOPMGetAggressiveness

Retrieves the current value of one of the aggressiveness factors in IOKit Power Management.

IOPMSchedulePowerEvent

Schedule the machine to wake from sleep, power on, go to sleep, or shutdown.

IOPMSetAggressiveness

Sets one of the aggressiveness factors in IOKit Power Management.

IOPMSleepEnabled

Tells whether the system supports full sleep, or just doze

IOPMSleepSystem

Request that the system initiate sleep.

IORegisterApp

Connects the caller to an IOService for the purpose of receiving power state change notifications for the device controlled by the IOService.

IORegisterForSystemPower

Connects the caller to the Root Power Domain IOService for the purpose of receiving sleep & wake notifications for the system. Does not provide system shutdown and restart notifications.

The caller acknowledges notification of a power state change on a device it has registered for notifications for via IORegisterForSystemPower or IORegisterApp.

IOReturn IOAllowPowerChange (
    io_connect_t kernelPort,
    long notificationID ) ;  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Discussion

Must be used when handling kIOMessageCanSystemSleep and kIOMessageSystemWillSleep messages from IOPMrootDomain system power. The caller should not call IOAllowPowerChange in response to any messages except for these two.

Availability

Introduced in Mac OS X v10.0.

The caller denies an idle system sleep power state change.

IOReturn IOCancelPowerChange (
    io_connect_t kernelPort,
    long notificationID ) ;  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Discussion

Should only called in response to kIOMessageCanSystemSleep messages from IOPMrootDomain. IOCancelPowerChange has no meaning for responding to kIOMessageSystemWillSleep (which is non-abortable) or any other messages.

When an app responds to a kIOMessageCanSystemSleep message by calling IOCancelPowerChange, the app vetos the idle sleep request. The system will stay awake. The idle timer will elapse again after a period of inactivity, and the system will send out the same kIOMessageCanSystemSleep message, and interested applications will respond gain.

Availability

Introduced in Mac OS X v10.0.

Indicates how user activity, battery level, and thermal level each contribute to the overall "SystemLoadAdvisory" level. In the future, this combined level may represent new levels as well.

CFDictionaryRef IOCopySystemLoadAdvisoryDetailed(
    void);  

Return Value

Returns a CFDictionaryRef, or NULL on error. Caller must release the returned dictionary.

Discussion

See dictionary keys defined above.

Disconnects the caller from an IOService after receiving power state change notifications from the IOService. (Caller must also release IORegisterApp's return io_connect_t and returned IONotificationPortRef for complete clean-up).

IOReturn IODeregisterApp (
    io_object_t *notifier );  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Availability

Introduced in Mac OS X v10.0.

Disconnects the caller from the Root Power Domain IOService after receiving system power state change notifications. (Caller must also destroy the IONotificationPortRef returned from IORegisterForSystemPower.)

IOReturn IODeregisterForSystemPower (
    io_object_t *notifier ) ;  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Availability

Introduced in Mac OS X v10.0.

Returns a hint about whether now would be a good time to perform time-insensitive work.

IOSystemLoadAdvisoryLevel IOGetSystemLoadAdvisory(
    void );  

Return Value

IOSystemLoadAdvisoryLevel - one of: kIOSystemLoadAdvisoryLevelGreat - A Good time to perform time-insensitive work. kIOSystemLoadAdvisoryLevelOK - An OK time to perform time-insensitive work. kIOSystemLoadAdvisoryLevelBad - A Bad time to perform time-insensitive work.

Discussion

Based on user and system load, IOGetSystemLoadAdvisory determines "better" and "worse" times to run optional or time-insensitive CPU or disk work.

Applications may use this result to avoid degrading the user experience. If it is a "Bad" or "OK" time to perform work, applications should slow down and perform work less aggressively.

There is no guarantee that the system will ever be in "Great" condition to perform work - all essential work must still be performed even in "Bad", or "OK" times. Completely optional work, such as updating caches, may be postponed indefinitely.

Note: You may more efficiently read the SystemLoadAdvisory level using notify_get_state() instead of IOGetSystemLoadAdvisory. The results are identical. notify_get_state() requires that you pass the token argument received by registering for SystemLoadAdvisory notifications.

Dynamically requests a system behavior from the power management system.

IOReturn IOPMAssertionCreate(
    CFStringRef AssertionType, 
    IOPMAssertionLevel AssertionLevel, 
    IOPMAssertionID *AssertionID)  ;  

Parameters

Return Value

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

Discussion

IOPMAssertionCreate is deprecated in favor of IOPMAssertionCreateWithName. Please use the named portion of this API instead for greater accountability. No special privileges necessary to make this call - any process may activate a power assertion.

Availability

Introduced in Mac OS X v10.5, but later deprecated in Mac OS X v10.6. Introduced in iPhone OS v2.0, but later deprecated in iPhone OS v2.1.

Dynamically requests a system behavior from the power management system.

IOReturn IOPMAssertionCreateWithName( 
    CFStringRef AssertionType, 
    IOPMAssertionLevel AssertionLevel, 
    CFStringRef AssertionName, 
    IOPMAssertionID *AssertionID) ;  

Parameters

Return Value

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

Discussion

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

Availability

Introduced in Mac OS X v10.6.

Releases the behavior requested in IOPMAssertionCreate

IOReturn IOPMAssertionRelease(
    IOPMAssertionID AssertionID) ;  

Parameters

Return Value

Returns kIOReturnSuccess on success

Discussion

All calls to IOPMAssertionCreate must be paired with calls to IOPMAssertionRelease.

Availability

Introduced in Mac OS X v10.5.

Cancel a previously scheduled power event.

IOReturn IOPMCancelScheduledPowerEvent(
    CFDateRef time_to_wake,
    CFStringRef my_id,
    CFStringRef type);  

Parameters

Return Value

kIOReturnSuccess on success, otherwise on failure

Discussion

Arguments mirror those to IOPMSchedulePowerEvent. All arguments must match the original arguments from when the power on was scheduled. Must be called as root.

Returns a dictionary mapping processes to the assertions they are holding active.

IOReturn IOPMCopyAssertionsByProcess(
    CFDictionaryRef *AssertionsByPID) ;  

Parameters

Return Value

Returns kIOReturnSuccess on success.

Discussion

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

Availability

Introduced in Mac OS X v10.5.

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

IOReturn IOPMCopyAssertionsStatus(
    CFDictionaryRef *AssertionsStatus) ;  

Parameters

Return Value

Returns kIOReturnSuccess on success.

Discussion

Notes: One process may have multiple assertions. Several processes may have asserted the same assertion to different levels. The system-wide level is the maximum of these assertions' levels.

Availability

Introduced in Mac OS X v10.5.

Request raw battery data from the system.

IOReturn IOPMCopyBatteryInfo(
    mach_port_t masterPort,
    CFArrayRef *info ) ;  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Discussion

WARNING! IOPMCoyBatteryInfo is unsupported on ALL Intel CPU based systems. For PPC CPU based systems, it remains not recommended. For almost all purposes, developers should use the richer IOPowerSources API (with change notifications) instead of using IOPMCopyBatteryInfo. Keys to decipher IOPMCopyBatteryInfo's return CFArray exist in IOPM.h.

Availability

Introduced in Mac OS X v10.0.

List all scheduled system power events

CFArrayRef IOPMCopyScheduledPowerEvents(
    void);  

Return Value

A CFArray of CFDictionaries of power events. The CFArray must be released by the caller. NULL if there are no scheduled events.

Discussion

Returns a CFArray of CFDictionaries of power events. Each CFDictionary contains keys for CFSTR(kIOPMPowerEventTimeKey), CFSTR(kIOPMPowerEventAppNameKey), and CFSTR(kIOPMPowerEventTypeKey).

Finds the Root Power Domain IOService.

io_connect_t IOPMFindPowerManagement(
    mach_port_t master_device_port ) ;  

Parameters

Return Value

Returns a io_connect_t handle on the root domain. Must be released with IOServiceClose() when done.

Availability

Introduced in Mac OS X v10.0.

Retrieves the current value of one of the aggressiveness factors in IOKit Power Management.

IOReturn IOPMGetAggressiveness (
    io_connect_t fb,
    unsigned long type,
    unsigned long *aggressiveness ) ;  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Availability

Introduced in Mac OS X v10.0.

Schedule the machine to wake from sleep, power on, go to sleep, or shutdown.

IOReturn IOPMSchedulePowerEvent(
    CFDateRef time_to_wake,
    CFStringRef my_id,
    CFStringRef type);  

Parameters

Return Value

kIOReturnSuccess on success, otherwise on failure

Discussion

This event will be added to the system's queue of power events and stored persistently on disk. The sleep and shutdown events present a graphical warning and allow a console user to cancel the event. Must be called as root.

Sets one of the aggressiveness factors in IOKit Power Management.

IOReturn IOPMSetAggressiveness (
    io_connect_t fb,
    unsigned long type,
    unsigned long aggressiveness ) ;  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Availability

Introduced in Mac OS X v10.0.

Tells whether the system supports full sleep, or just doze

boolean_t IOPMSleepEnabled (
    void );  

Return Value

Returns true if the system supports sleep, false if some hardware prevents full sleep.

Availability

Introduced in Mac OS X v10.0.

Request that the system initiate sleep.

IOReturn IOPMSleepSystem (
    io_connect_t fb );  

Parameters

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Discussion

For security purposes, caller must be root or the console user.

Availability

Introduced in Mac OS X v10.0.

Connects the caller to an IOService for the purpose of receiving power state change notifications for the device controlled by the IOService.

io_connect_t IORegisterApp(
    void *refcon, 
    io_service_t theDriver, 
    IONotificationPortRef *thePortRef, 
    IOServiceInterestCallback callback, 
    io_object_t *notifier ) ;  

Parameters

Return Value

Returns a io_connect_t session for the IOService or MACH_PORT_NULL if request failed. Caller must close return value via IOServiceClose() after calling IODeregisterApp on the notifier argument.

Discussion

IORegisterApp requires that the IOService of interest implement an IOUserClient. In addition, that IOUserClient must implement the allowPowerChange and cancelPowerChange methods defined in IOPMLibDefs.h. If you're interested in receiving power state notifications from a device without an IOUserClient, try using IOServiceAddInterestNotification with interest type gIOGeneralInterest instead.

Availability

Introduced in Mac OS X v10.0.

Connects the caller to the Root Power Domain IOService for the purpose of receiving sleep & wake notifications for the system. Does not provide system shutdown and restart notifications.

io_connect_t IORegisterForSystemPower (
    void *refcon, 
    IONotificationPortRef *thePortRef, 
    IOServiceInterestCallback callback, 
    io_object_t *notifier ) ;  

Parameters

Return Value

Returns a io_connect_t session for the IOPMrootDomain or MACH_PORT_NULL if request failed. Caller must close return value via IOServiceClose() after calling IODeregisterForSystemPower on the notifier argument.

Discussion

Provides sleep/wake notifications to applications. Requires that applications acknowledge some, but not all notifications. Register for sleep/wake notifications will deliver these messages over the sleep/wake lifecycle:

- kIOMessageSystemWillSleep is delivered at the point the system is initiating a non-abortable sleep. Callers MUST acknowledge this event by calling IOAllowPowerChange. If a caller does not acknowledge the sleep notification, the sleep will continue anyway after a 30 second timeout (resulting in bad user experience). Delivered before any hardware is powered off. - kIOMessageSystemWillPowerOn is delivered at early wakeup time, before most hardware has been powered on. Be aware that any attempts to access disk, network, the display, etc. may result in errors or blocking your process until those resources become avaiable. Caller must NOT acknowledge kIOMessageSystemWillPowerOn; the caller must simply return from its handler. - kIOMessageSystemHasPoweredOn is delivered at wakeup completion time, after all device drivers and hardware have handled the wakeup event. Expect this event 1-5 or more seconds after initiating system awkeup. Caller must NOT acknowledge kIOMessageSystemHasPoweredOn; the caller must simply return from its handler. - kIOMessageCanSystemSleep indicates the system is pondering an idle sleep, but gives apps the chance to veto that sleep attempt. Caller must acknowledge kIOMessageCanSystemSleep by calling IOAllowPowerChange or IOCancelPowerChange. Calling IOAllowPowerChange will not veto the sleep; any app that calls IOCancelPowerChange will veto the idle sleep. A kIOMessageCanSystemSleep notification will be followed up to 30 seconds later by a kIOMessageSystemWillSleep message. or a kIOMessageSystemWillNotPowerOn message. - kIOMessageSystemWillNotPowerOn is delivered when some app client has vetoed an idle sleep request. kIOMessageSystemWillNotPowerOn may follow a kIOMessageCanSystemSleep notification, but will not otherwise be sent. Caller must NOT acknowledge kIOMessageSystemWiillNotPowerOn; the caller must simply return from its handler.

To deregister for sleep/wake notifications, the caller must make two calls, in this order: - Call IODeregisterForSystemPower with the 'notifier' argument returned here. - Then call IONotificationPortDestroy passing the 'thePortRef' argument returned here.

Availability

Introduced in Mac OS X v10.0.

Typedefs

IOPMAssertionID

Type for AssertionID arguments to IOPMAssertionCreate and IOPMAssertionRelease

IOPMAssertionLevel

Type for AssertionLevel argument to IOPMAssertionCreate

IOSystemLoadAdvisoryLevel

Return type for IOGetSystemLoadAdvisory

Type for AssertionID arguments to IOPMAssertionCreate and IOPMAssertionRelease

typedef uint32_t IOPMAssertionID;  

Type for AssertionLevel argument to IOPMAssertionCreate

typedef uint32_t IOPMAssertionLevel;  

Return type for IOGetSystemLoadAdvisory

typedef int IOSystemLoadAdvisoryLevel;  

Discussion

Value is one of kIOSystemLoadAdvisoryLevelGreat, kIOSystemLoadAdvisoryLevelOK, or kIOSystemLoadAdvisoryLevelBad.

Enumerated Types

Assertion

Level for an enabled assertion, passed as an argument to IOPMAssertionCreate

kIOPMNullAssertionID

This value represents a non-initialized assertion ID

Level for an enabled assertion, passed as an argument to IOPMAssertionCreate

enum {  
    kIOPMAssertionLevelOff = 0,   
    kIOPMAssertionLevelOn = 255 
};  

Constants

Discussion

Levels

This value represents a non-initialized assertion ID

enum { 
    kIOPMNullAssertionID = 0 
};  

Macro Definitions

kIOPMAssertionLevelKey

The CFDictionary key for assertion level in dictionaries returned by IOPMCopyAssertionsByProcess.

kIOPMAssertionNameKey

The CFDictionary key for assertion name in dictionaries returned by IOPMCopyAssertionsByProcess.

kIOPMAssertionTypeKey

The CFDictionary key for assertion type in dictionaries returned by IOPMCopyAssertionsByProcess.

kIOPMAssertionTypeNoDisplaySleep

Use as AssertionType argument to IOPMAssertionCreate. The display will not sleep when enabled (consequently the system will not sleep).

kIOPMAssertionTypeNoIdleSleep

Use as AssertionType argument to IOPMAssertionCreate. The system will not sleep when enabled (display may sleep).

kIOSystemLoadAdvisoryBatteryLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

kIOSystemLoadAdvisoryCombinedLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

kIOSystemLoadAdvisoryNotifyName

The notifcation by this name fires when system "SystemLoadAdvisory" status changes.

kIOSystemLoadAdvisoryThermalLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

kIOSystemLoadAdvisoryUserLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

The CFDictionary key for assertion level in dictionaries returned by IOPMCopyAssertionsByProcess.

#define kIOPMAssertionLevelKey CFSTR("AssertLevel") 

The CFDictionary key for assertion name in dictionaries returned by IOPMCopyAssertionsByProcess.

#define kIOPMAssertionNameKey CFSTR("AssertName") 

Discussion

Name is specified by the assertion creator, and reflects the calling process and the activity being handled by the assertion.

The CFDictionary key for assertion type in dictionaries returned by IOPMCopyAssertionsByProcess.

#define kIOPMAssertionTypeKey CFSTR("AssertType") 

Use as AssertionType argument to IOPMAssertionCreate. The display will not sleep when enabled (consequently the system will not sleep).

#define kIOPMAssertionTypeNoDisplaySleep CFSTR("NoDisplaySleepAssertion") 

Use as AssertionType argument to IOPMAssertionCreate. The system will not sleep when enabled (display may sleep).

#define kIOPMAssertionTypeNoIdleSleep CFSTR("NoIdleSleepAssertion") 

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

#define kIOSystemLoadAdvisoryBatteryLevelKey CFSTR("BatteryLevel") 

Discussion

Indicates battery constraints on the current SystemLoadAdvisory level.

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

#define kIOSystemLoadAdvisoryCombinedLevelKey CFSTR("CombinedLevel") 

Discussion

Provides a combined level based on UserLevel, BatteryLevel, and ThermalLevels; the combined level is the minimum of these levels. In the future, this combined level may represent new levels as well. The combined level is identical to the value returned by IOGetSystemLoadAdvisory().

The notifcation by this name fires when system "SystemLoadAdvisory" status changes.

#define kIOSystemLoadAdvisoryNotifyName "com.apple.system.powermanagement.SystemLoadAdvisory" 

Discussion

Pass this string as an argument to register via notify(3). You can query SystemLoadAdvisory state via notify_get_state() when this notification fires - this is more efficient than calling IOGetSystemLoadAdvisory(), and returns an identical combined SystemLoadAdvisory value.

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

#define kIOSystemLoadAdvisoryThermalLevelKey CFSTR("ThermalLevel") 

Discussion

Indicates thermal constraints on the current SystemLoadAdvisory level.

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed

#define kIOSystemLoadAdvisoryUserLevelKey CFSTR("UserLevel") 

Discussion

Indicates user activity constraints on the current SystemLoadAdvisory level.

Last Updated: 2009-10-15