IOPowerSources.h

Includes:
<sys/cdefs.h>

Introduction

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.



Groups

Power Source Descriptions

Group members:

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.

IOPSGetPowerSourceDescription

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

IOPSGetProvidingPowerSourceType(CFTypeRef)

Indicates the power source the computer is currently drawing from.

IOPSGetProvidingPowerSourceType(CFTypeRef)

Indicates the power source the computer is currently drawing from.

IOPSNotificationCreateRunLoopSource

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

 

Low Power Warnings

Group members:

IOPSGetBatteryWarningLevel

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

 

Quick Power Source Info

Group members:

IOPSGetTimeRemainingEstimate

Returns the estimated minutes remaining until all power sources (battery and/or UPS's) are empty, or returns kIOPSTimeRemainingUnlimited if attached to an unlimited power source.


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.

IOPSGetProvidingPowerSourceType(CFTypeRef)

Indicates the power source the computer is currently drawing from.

IOPSGetProvidingPowerSourceType(CFTypeRef)

Indicates the power source the computer is currently drawing from.

IOPSGetTimeRemainingEstimate

Returns the estimated minutes remaining until all power sources (battery and/or UPS's) are empty, or returns kIOPSTimeRemainingUnlimited if attached to an unlimited power source.

IOPSNotificationCreateRunLoopSource

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


IOPSCopyExternalPowerAdapterDetails


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.


IOPSCopyPowerSourcesInfo


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.


IOPSCopyPowerSourcesList


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

CFArrayRef IOPSCopyPowerSourcesList(
    CFTypeRef blob);  
Parameters
blob

Takes the CFTypeRef returned by IOPSCopyPowerSourcesInfo()

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.


IOPSGetBatteryWarningLevel


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.


IOPSGetPowerSourceDescription


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

CFDictionaryRef IOPSGetPowerSourceDescription(
    CFTypeRef blob,
    CFTypeRef ps);  
Parameters
blob

The CFTypeRef returned by IOPSCopyPowerSourcesInfo()

ps

One of the CFTypeRefs in the CFArray returned by IOPSCopyPowerSourcesList()

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.


IOPSGetProvidingPowerSourceType(CFTypeRef)


Indicates the power source the computer is currently drawing from.

CFStringRef IOPSGetProvidingPowerSourceType(
    CFTypeRef snapshot);  
Parameters
snapshot

The CFTypeRef returned by IOPSCopyPowerSourcesInfo(); caller may pass NULL.

Return Value

One of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey)

Discussion

Determines which power source is providing power.


IOPSGetProvidingPowerSourceType(CFTypeRef)


Indicates the power source the computer is currently drawing from.

CFStringRef IOPSGetProvidingPowerSourceType(
    CFTypeRef snapshot);  
Parameters
snapshot

The CFTypeRef returned by IOPSCopyPowerSourcesInfo()

Return Value

One of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey)

Discussion

Determines which power source is providing power.


IOPSGetTimeRemainingEstimate


Returns the estimated minutes remaining until all power sources (battery and/or UPS's) are empty, or returns kIOPSTimeRemainingUnlimited if attached to an unlimited power source.

CFTimeInterval IOPSGetTimeRemainingEstimate(
    void);  
Return Value

Returns kIOPSTimeRemainingUnknown if the OS cannot determine the time remaining.

Returns kIOPSTimeRemainingUnlimited if the system has an unlimited power source.

Otherwise returns a positive number of type CFTimeInterval, indicating the time remaining in seconds until all power sources are depleted.

Discussion

If attached to an "Unlimited" power source, like AC power or any external source, the return value is kIOPSTimeRemainingUnlimited

If the system is on "Limited" power, like a battery or UPS, but is still calculating the time remaining, which may take several seconds after each system power event (e.g. waking from sleep, or unplugging AC Power), the return value is kIOPSTimeRemainingUnknown

Otherwise, if the system is on "Limited" power and the system has an accurate time remaining estimate, the system returns a CFTimeInterval estimate of the time remaining until the system is out of battery power.

If you require more detailed battery information, use IOPSCopyPowerSourcesInfo> and IOPSGetPowerSourceDescription>.


IOPSNotificationCreateRunLoopSource


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

CFRunLoopSourceRef IOPSNotificationCreateRunLoopSource(
    IOPowerSourceCallbackType callback,
    void *context);  
Parameters
callback

A function to be called whenever any power source is added, removed, or changes.

context

Any user-defined pointer, passed to the IOPowerSource callback.

Return Value

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

Discussion

Returns a CFRunLoopSourceRef for scheduling with your CFRunLoop. If your project does not use a CFRunLoop, you can alternatively receive notifications via mach port, dispatch, or signal, via notify.h using the name kIOPSTimeRemainingNotificationKey


Typedefs

IOPSLowBatteryWarningLevel

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


IOPSLowBatteryWarningLevel


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

typedef enum {  
    kIOPSLowBatteryWarningNone = 1,   
    kIOPSLowBatteryWarningEarly = 2,   
    kIOPSLowBatteryWarningFinal = 3 
} IOPSLowBatteryWarningLevel;  
Constants
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.

kIOPSTimeRemainingNotificationKey

C-string key for a notification that fires when the power source(s) time remaining changes.

kIOPSTimeRemainingUnknown

Possible return value from IOPSGetTimeRemainingEstimate

kIOPSTimeRemainingUnlimited

Possible return value from IOPSGetTimeRemainingEstimate


kIOPSNotifyLowBattery


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" 

kIOPSTimeRemainingNotificationKey


C-string key for a notification that fires when the power source(s) time remaining changes.

#define kIOPSTimeRemainingNotificationKey "com.apple.system.powersources.timeremaining" 
Discussion

Use notify(3) API to register for notifications.


kIOPSTimeRemainingUnknown


Possible return value from IOPSGetTimeRemainingEstimate

#define kIOPSTimeRemainingUnknown  
Discussion

Indicates the system is connected to a limited power source, but the system is still calculating a time remaining estimate. Check for a valid estimate again when the notification kIOPSPowerSourcesNotificationKey fires.


kIOPSTimeRemainingUnlimited


Possible return value from IOPSGetTimeRemainingEstimate

#define kIOPSTimeRemainingUnlimited  
Discussion

Indicates the system is connected to an external power source, without a time limit.