IOPowerSources.h

Overview

IOPowerSources provides uniform access to the state of power sources attached to the system. You can receive a change notification when any power source data changes. "Power sources" currently include batteries and UPS devices.
The header follows CF semantics in that it is the caller's responsibility to CFRelease() anything returned by a "Copy" function, and the caller should not CFRelease() anything returned by a "Get" function.

Power Source Descriptions

Low Power Warnings

Group members:

Functions

IOPSCopyExternalPowerAdapterDetails

Returns a CFDictionary that describes the attached (AC) external power adapter (if any external power adapter is attached.

IOPSCopyPowerSourcesInfo

Returns a blob of Power Source information in an opaque CFTypeRef.

IOPSCopyPowerSourcesList

Returns a CFArray of Power Source handles, each of type CFTypeRef.

IOPSGetBatteryWarningLevel

Indicates whether the system is at a low battery warning level.

IOPSGetPowerSourceDescription

Returns a CFDictionary with readable information about the specific power source.

IOPSNotificationCreateRunLoopSource

Returns a CFRunLoopSourceRef that notifies the caller when power source information changes.

Returns a CFDictionary that describes the attached (AC) external power adapter (if any external power adapter is attached.

CFDictionaryRef IOPSCopyExternalPowerAdapterDetails(
    void);  

Return Value

Returns a CFDictionary on success. Caller must release the returned dictionary. If no adapter is attached, or if there's an error, returns NULL.

Discussion

Use the kIOPSPowerAdapter... keys described in IOPSKeys.h to interpret the returned CFDictionary.

Returns a blob of Power Source information in an opaque CFTypeRef.

CFTypeRef IOPSCopyPowerSourcesInfo(
    void);  

Return Value

NULL if errors were encountered, a CFTypeRef otherwise. Caller must CFRelease() the return value when done accessing it.

Discussion

Clients should not directly access data in the returned CFTypeRef - they should use the accessor functions IOPSCopyPowerSourcesList and IOPSGetPowerSourceDescription, instead.

Returns a CFArray of Power Source handles, each of type CFTypeRef.

CFArrayRef IOPSCopyPowerSourcesList(
    CFTypeRef blob);  

Parameters

Return Value

Returns NULL if errors were encountered, otherwise a CFArray of CFTypeRefs. Caller must CFRelease() the returned CFArrayRef.

Discussion

The caller shouldn't directly access the CFTypeRefs, but should use IOPSGetPowerSourceDescription on each member of the CFArrayRef.

Indicates whether the system is at a low battery warning level.

IOPSLowBatteryWarningLevel IOPSGetBatteryWarningLevel(
    void);  

Discussion

If your app runs in full screen mode and occludes OS X's battery monitor's low battery warnings, you should alert the user at least when the system is in kIOPSLowBatteryWarnFinal.

Returns a CFDictionary with readable information about the specific power source.

CFDictionaryRef IOPSGetPowerSourceDescription(
    CFTypeRef blob,
    CFTypeRef ps);  

Parameters

Return Value

Returns NULL if an error was encountered, otherwise a CFDictionary. Caller should NOT release the returned CFDictionary - it will be released as part of the CFTypeRef returned by IOPSCopyPowerSourcesInfo().

Discussion

See the C-strings defined in IOPSKeys.h for specific keys into the dictionary. Don't expect all keys to be present in any dictionary. Some power sources, for example, may not support the "Time Remaining To Empty" key and it will not be present in their dictionaries.

Returns a CFRunLoopSourceRef that notifies the caller when power source information changes.

CFRunLoopSourceRef IOPSNotificationCreateRunLoopSource(
    IOPowerSourceCallbackType,
    void *);  

Parameters

Return Value

Returns NULL if an error was encountered, otherwise a CFRunLoopSource. Caller must release the CFRunLoopSource.

Globals

kIOPSLowBatteryWarningFinal

The battery can provide no more than 10 minutes of runtime.

kIOPSLowBatteryWarningFinal

The battery can provide no more than 10 minutes of runtime.

The battery can provide no more than 10 minutes of runtime.

kIOPSLowBatteryWarningNone = 1,   kIOPSLowBatteryWarningEarly = 2,   kIOPSLowBatteryWarningFinal = 3 
} IOPSLowBatteryWarningLevel;  

Discussion

OS X makes no guarantees that the system shall remain in Final Warning for 10 minutes. Batteries are frequently calibrated differently and may provide runtime for more or less than the estimated 10 minutes.

The battery can provide no more than 10 minutes of runtime.

kIOPSLowBatteryWarningNone = 1,   kIOPSLowBatteryWarningEarly = 2,   kIOPSLowBatteryWarningFinal = 3 
} IOPSLowBatteryWarningLevel;  

Discussion

OS X makes no guarantees that the system shall remain in Final Warning for 10 minutes. Batteries are frequently calibrated differently and may provide runtime for more or less than the estimated 10 minutes.

Macro Definitions

kIOPSNotifyLowBattery

Notify(3) key. The system delivers notifications on this key when the battery time remaining drops into a warnable level.

Notify(3) key. The system delivers notifications on this key when the battery time remaining drops into a warnable level.

#define kIOPSNotifyLowBattery "com.apple.system.powersources.lowbattery" 

Last Updated: 2009-10-15