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

IOPowerSources.h

Include Path:	<IOKit/ps>
Path:	/System/Library/Frameworks/IOKit.framework/Versions/A/Headers/ps/IOPowerSources.h
See Also:	IOPSKeys
Includes:	<sys/cdefs.h>

Overview

This header 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.

Functions

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.
IOPSNotificationCreateRunLoopSource: Returns a CFRunLoopSourceRef that notifies the caller when power source information changes.

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.

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.

IOPSNotificationCreateRunLoopSource

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

CFRunLoopSourceRef IOPSNotificationCreateRunLoopSource(
    IOPowerSourceCallbackType,
    void *);

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.

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