IOPowerSources.h
IntroductionIOPowerSources 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. GroupsPower Source DescriptionsGroup members:
Low Power WarningsGroup members:
Quick Power Source InfoGroup members:
Functions
IOPSCopyExternalPowerAdapterDetailsReturns a CFDictionary that describes the attached (AC) external power adapter (if any external power adapter is attached. CFDictionaryRef IOPSCopyExternalPowerAdapterDetails( void); Return ValueReturns a CFDictionary on success. Caller must release the returned dictionary. If no adapter is attached, or if there's an error, returns NULL. DiscussionUse the kIOPSPowerAdapter... keys described in IOPSKeys.h to interpret the returned CFDictionary. IOPSCopyPowerSourcesInfoReturns a blob of Power Source information in an opaque CFTypeRef. CFTypeRef IOPSCopyPowerSourcesInfo( void); Return ValueNULL if errors were encountered, a CFTypeRef otherwise. Caller must CFRelease() the return value when done accessing it. DiscussionClients should not directly access data in the returned CFTypeRef - they should use the accessor functions IOPSCopyPowerSourcesList and IOPSGetPowerSourceDescription, instead. IOPSCopyPowerSourcesListReturns a CFArray of Power Source handles, each of type CFTypeRef. CFArrayRef IOPSCopyPowerSourcesList( CFTypeRef blob); ParametersReturn ValueReturns NULL if errors were encountered, otherwise a CFArray of CFTypeRefs. Caller must CFRelease() the returned CFArrayRef. DiscussionThe caller shouldn't directly access the CFTypeRefs, but should use IOPSGetPowerSourceDescription on each member of the CFArrayRef. IOPSGetBatteryWarningLevelIndicates whether the system is at a low battery warning level. IOPSLowBatteryWarningLevel IOPSGetBatteryWarningLevel( void); DiscussionIf 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. IOPSGetPowerSourceDescriptionReturns a CFDictionary with readable information about the specific power source. CFDictionaryRef IOPSGetPowerSourceDescription( CFTypeRef blob, CFTypeRef ps); ParametersReturn ValueReturns 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(). DiscussionSee 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); ParametersReturn ValueOne of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey) DiscussionDetermines which power source is providing power. IOPSGetProvidingPowerSourceType(CFTypeRef)Indicates the power source the computer is currently drawing from. CFStringRef IOPSGetProvidingPowerSourceType( CFTypeRef snapshot); ParametersReturn ValueOne of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey) DiscussionDetermines which power source is providing power. IOPSGetTimeRemainingEstimateReturns the estimated minutes remaining until all power sources
(battery and/or UPS's) are empty, or returns CFTimeInterval IOPSGetTimeRemainingEstimate( void); Return ValueReturns Returns Otherwise returns a positive number of type CFTimeInterval, indicating the time remaining in seconds until all power sources are depleted. DiscussionIf attached to an "Unlimited" power source, like AC power or any external source, the
return value is 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
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
IOPSNotificationCreateRunLoopSourceReturns a CFRunLoopSourceRef that notifies the caller when power source information changes. CFRunLoopSourceRef IOPSNotificationCreateRunLoopSource( IOPowerSourceCallbackType callback, void *context); ParametersReturn ValueReturns NULL if an error was encountered, otherwise a CFRunLoopSource. Caller must release the CFRunLoopSource. DiscussionReturns 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 Typedefs
IOPSLowBatteryWarningLevelThe battery can provide no more than 10 minutes of runtime. typedef enum { kIOPSLowBatteryWarningNone = 1, kIOPSLowBatteryWarningEarly = 2, kIOPSLowBatteryWarningFinal = 3 } IOPSLowBatteryWarningLevel; ConstantsDiscussionOS 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
kIOPSNotifyLowBatteryNotify(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" kIOPSTimeRemainingNotificationKeyC-string key for a notification that fires when the power source(s) time remaining changes. #define kIOPSTimeRemainingNotificationKey "com.apple.system.powersources.timeremaining" DiscussionUse notify(3) API to register for notifications. kIOPSTimeRemainingUnknownPossible return value from #define kIOPSTimeRemainingUnknown DiscussionIndicates 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
kIOPSTimeRemainingUnlimitedPossible return value from #define kIOPSTimeRemainingUnlimited DiscussionIndicates the system is connected to an external power source, without a time limit. |