ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOPMLib.h

Includes:

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.

Groups

Assertions

Group members:

IOPMAssertionCreate

Dynamically requests a system behavior from the power management system.

IOPMAssertionRelease

Releases the behavior requested in IOPMAssertionCreate

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.

Notifications

Group members:

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 negatively acknowledges notification of a power state change on a device it is interested in. This prevents the state change.

IODeregisterForSystemPower

Disconnects the caller from the Root Power Domain IOService after receiving system power state change notifications. (Caller must also release IORegisterForSystemPower'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 release IORegisterForSystemPower's return io_connect_t and returned IONotificationPortRef for complete clean-up).

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, ShutDown, PowerUp notifications for the System.

Scheduled

Events

Group members:

IOPMCancelScheduledPowerEvent

Cancel a previously scheduled power event.

IOPMCopyScheduledPowerEvents

List all scheduled system power events

IOPMSchedulePowerEvent

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

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 negatively acknowledges notification of a power state change on a device it is interested in. This prevents the state change.
IODeregisterForSystemPower: Disconnects the caller from the Root Power Domain IOService after receiving system power state change notifications. (Caller must also release IORegisterForSystemPower'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 release IORegisterForSystemPower's return io_connect_t and returned IONotificationPortRef for complete clean-up).
IOPMAssertionCreate: 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, ShutDown, PowerUp notifications for the System.

IOAllowPowerChange

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

kernelPort: Port used to communicate to the kernel, from IORegisterApp or IORegisterForSystemPower.
notificationID: A copy of the notification ID which came as part of the power state change notification being acknowledged.

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.

IOCancelPowerChange

The caller negatively acknowledges notification of a power state change on a device it is interested in. This prevents the state change.

IOReturn IOCancelPowerChange (
    io_connect_t kernelPort,
    long notificationID );

Parameters

kernelPort: Port used to communicate to the kernel, from IORegisterApp or IORegisterForSystemPower.
notificationID: A copy of the notification ID which came as part of the power state change notification being acknowledged.

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Discussion

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

IODeregisterForSystemPower

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

IOReturn IODeregisterForSystemPower (
    io_object_t *notifier );

Parameters

notifier: An object from IORegisterForSystemPower.

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

IODeregisterForSystemPower.

IOReturn IODeregisterForSystemPower (
    io_object_t *notifier );

Parameters

notifier: An object from IORegisterForSystemPower.

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

IOPMAssertionCreate

Dynamically requests a system behavior from the power management system.

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

Parameters

AssertionType: The CFString assertion type to request from the PM system.
AssertionLevel: Pass kIOPMAssertionLevelOn or kIOPMAssertionLevelOff.
AssertionID: On success, a unique id will be returned in this parameter.

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.

IOPMAssertionRelease

Releases the behavior requested in IOPMAssertionCreate

IOReturn IOPMAssertionRelease(
    IOPMAssertionID AssertionID);

Parameters

AssertionID: The assertion_id, returned from IOPMAssertionCreate, to cancel.

Return Value

Returns kIOReturnSuccess on success

Discussion

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

IOPMCancelScheduledPowerEvent

Cancel a previously scheduled power event.

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

Parameters

time_to_wake: Cancel entry with this date and time.
my_id: Cancel entry with this name.
type: Type to cancel

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.

IOPMCopyAssertionsByProcess

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

IOReturn IOPMCopyAssertionsByProcess(
    CFDictionaryRef *AssertionsByPID);

Parameters

AssertionsByPID: On success, this returns a dictionary of assertions per process. At the top level, keys to the CFDictionary are pids stored as CFNumbers (kCFNumberIntType). The value associated with each CFNumber pid is a CFArray of active assertions. Each entry in the CFArray is an assertion represented as a CFDictionary. See the keys kIOPMAssertionTypeKey and kIOPMAssertionLevelKey. Caller must CFRelease() this dictionary when done.

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.

IOPMCopyAssertionsStatus

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

IOReturn IOPMCopyAssertionsStatus(
    CFDictionaryRef *AssertionsStatus);

Parameters

AssertionsStatus: On success, this returns a CFDictionary 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. Caller must CFRelease() this dictionary when done.

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.

IOPMCopyBatteryInfo

Request raw battery data from the system.

IOReturn IOPMCopyBatteryInfo(
    mach_port_t masterPort,
    CFArrayRef *info );

Parameters

masterPort: The master port obtained from IOMasterPort(). Just pass MACH_PORT_NULL.
info: A CFArray of CFDictionaries containing raw battery data.

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.

IOPMCopyScheduledPowerEvents

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).

IOPMFindPowerManagement

Finds the Root Power Domain IOService.

io_connect_t IOPMFindPowerManagement(
    mach_port_t master_device_port );

Parameters

master_device_port: Just pass in MACH_PORT_NULL for master device port.

Return Value

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

IOPMGetAggressiveness

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

fb: Representation of the Root Power Domain from IOPMFindPowerManagement.
type: Specifies which aggressiveness factor is being retrieved.
type: Points to where to store the retrieved value of the aggressiveness factor.

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

IOPMSchedulePowerEvent

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

time_to_wake: Date and time that the system will power on/off.
my_id: A CFStringRef identifying the calling app by CFBundleIdentifier. May be NULL.
type: The type of power on you desire, either wake from sleep or power on. Choose from: CFSTR(kIOPMAutoWake) == wake machine, CFSTR(kIOPMAutoPowerOn) == power on machine, CFSTR(kIOPMAutoWakeOrPowerOn) == wake or power on, CFSTR(kIOPMAutoSleep) == sleep machine, CFSTR(kIOPMAutoShutdown) == power off machine, CFSTR(kIOPMAutoRestart) == restart the machine.

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.

IOPMSetAggressiveness

Sets one of the aggressiveness factors in IOKit Power Management.

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

Parameters

fb: Representation of the Root Power Domain from IOPMFindPowerManagement.
type: Specifies which aggressiveness factor is being set.
type: New value of the aggressiveness factor.

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

IOPMSleepEnabled

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.

IOPMSleepSystem

Request that the system initiate sleep.

IOReturn IOPMSleepSystem (
    io_connect_t fb );

Parameters

fb: Port used to communicate to the kernel, from IOPMFindPowerManagement.

Return Value

Returns kIOReturnSuccess or an error condition if request failed.

Discussion

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

IORegisterApp

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

refcon: Data returned on power state change notifications and not used by the kernel.
theDriver: Representation of the IOService, probably from IOServiceGetMatchingService.
thePortRef: Pointer to a port on which the caller will receive power state change notifications. The port is allocated by the calling application.
callback: A c-function which is called during the notification.
notifier: Pointer to a notifier which caller must keep and pass to subsequent call to IODeregisterApp.

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.

IORegisterForSystemPower

Connects the caller to the Root Power Domain IOService for the purpose of receiving Sleep, Wake, ShutDown, PowerUp notifications for the System.

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

Parameters

refcon: Data returned on power state change notifications and not used by the kernel.
thePortRef: Pointer to a port on which the caller will receive power state change notifications. The port is allocated by this function and must be later released by the caller (after IODeregisterForSystemPower).
callback: A c-function which is called during the notification.
notifier: On success, returns a pointer to a unique notifier which caller must keep and pass to a subsequent call to IODeregisterForSystemPower.

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.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11