1/* 2 * Copyright (c) 2002 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23/* 24 * HISTORY 25 * 26 */ 27 28#ifndef _IOKIT_IOPOWERSOURCES_H 29#define _IOKIT_IOPOWERSOURCES_H 30 31#include <sys/cdefs.h> 32__BEGIN_DECLS 33 34 35/*! 36 * @header IOPowerSources.h 37 * 38 * @discussion IOPowerSources provides uniform access to the state of power sources attached to the system. 39 * You can receive a change notification when any power source data changes. 40 * "Power sources" currently include batteries and UPS devices. 41 * 42 * The header follows CF semantics in that it is the caller's responsibility to 43 * CFRelease() anything returned by a "Copy" function, and the caller should not 44 * CFRelease() anything returned by a "Get" function. 45 */ 46 47/*! 48 * @functiongroup Low Power Warnings 49 */ 50 51/*! @constant kIOPSNotifyLowBattery 52 * 53 * @abstract Notify(3) key. IOKit posts kIOPSNotifyLowBattery notifications when the 54 * system is drawing from limited battery power, and the battery time 55 * remaining drops into a warnable level. 56 * 57 * See also kIOPSNotifyPowerSource, and kIOPSNotifyTimeRemaining 58 */ 59#define kIOPSNotifyLowBattery "com.apple.system.powersources.lowbattery" 60 61/*! 62 * @enum IOPSLowBatteryWarningLevel 63 * 64 * @discussion Possible return values from <code>@link IOPSGetBatteryWarningLevel@/link</code> 65 */ 66typedef enum { 67/*! @constant kIOPSLowBatteryWarningNone 68 * 69 * @abstract The system is not in a low battery situation, or is on drawing from an external power source. 70 * 71 * @discussion The system displays no low power warnings; neither should application clients of this 72 * API. 73 */ 74 kIOPSLowBatteryWarningNone = 1, 75 76/*! @constant kIOPSLowBatteryWarningEarly 77 * 78 * @abstract The system is in an early low battery situation. 79 * 80 * @discussion Per Apple's definition, the battery has dropped below 22% remaining power. 81 * OS X alerts the user by changing the color of BatteryMonitor to red. 82 * Warning the user is optional for full screen apps. 83 */ 84 kIOPSLowBatteryWarningEarly = 2, 85 86/*! @constant kIOPSLowBatteryWarningFinal 87 * 88 * @abstract The battery can provide no more than 10 minutes of runtime. 89 * 90 * @discussion OS X makes no guarantees that the system shall remain in Final Warning for 10 minutes. 91 * Batteries are frequently calibrated differently and may provide runtime 92 * for more, or less, than the estimated 10 minutes. 93 */ 94 kIOPSLowBatteryWarningFinal = 3 95} IOPSLowBatteryWarningLevel; 96 97/*! @function IOPSGetBatteryWarningLevel 98 * 99 * @abstract Indicates whether the system is at a low battery warning level. 100 * 101 * @discussion If your app runs in full screen mode and occludes OS X's battery monitor's low 102 * battery warnings, you should alert the user at least when the system 103 * is in kIOPSLowBatteryWarnFinal. 104 */ 105IOPSLowBatteryWarningLevel IOPSGetBatteryWarningLevel(void); 106 107/*! 108 * @functiongroup Quick Power Source Info 109 */ 110 111/*! 112 * @define kIOPSNotifyTimeRemaining 113 * C-string key for a notification of changes to any power source's time remaining estimate. 114 * IOKit also posts this notification when the active power source changes between AC, Battery, and UPS. 115 * 116 * If you only need to detect when the power source changes between AC, Battery, or UPS, please use 117 * <code>@link kIOPSNotifyPowerSource @/link</code>; your code will run less often and conserve battery life. 118 * 119 * See API <code>@link IOPSGetTimeRemainingEstimate @/link</code> to determine whether the active power source is 120 * limited or unlimited; and to determine the estimated time remaining until empty. 121 * 122 * Use notify(3) API to register for notifications. 123 */ 124#define kIOPSNotifyTimeRemaining "com.apple.system.powersources.timeremaining" 125#define kIOPSTimeRemainingNotificationKey kIOPSNotifyTimeRemaining 126 127/*! 128 * @define kIOPSNotifyPowerSource 129 * @abstract C-string key for a notification of changes to the active power source. 130 * @discussion Use this notification to discover when the active power source changes from AC power (unlimited/wall power), 131 * to Battery Power or UPS Power (limited power). IOKit will not deliver this notification when a battery's 132 * time remaining changes, only when the active power source changes. This makes it a more effiicent 133 * choice for clients only interested in differentiating AC vs Battery. 134 * 135 * See API <code>@link IOPSGetTimeRemainingEstimate @/link</code> to determine whether the active power source is 136 * limited or unlimited. 137 * 138 * Example: IOKit posts kIOPSNotifyPowerSource upon connecting or disconnecting AC power to a laptop. 139 * IOKit posts kIOPSNotifyPowerSource upon a UPS losing AC Power; as the system switches to a limited 140 * UPS battery power source. 141 * 142 * Use notify(3) API to register for notifications. 143 * */ 144#define kIOPSNotifyPowerSource "com.apple.system.powersources.source" 145 146/*! 147 * @define kIOPSNotifyAttach 148 * @abstract C-string key for a notification when a power source is attached or detached. 149 * @discussion Example: IOKit posts kIOPSNotifyAttach upon detection of internal battery. 150 * IOKit posts kIOPSNotifyAttach when a user attaches or detaches an external UPS. 151 * 152 * Note that IOKit doesn't deliver kIOPSNotifyAttach upon plugging or unplugging AC Power to a laptop; see 153 * <code>@link kIOPSNotifyPowerSource@/link</code> for changes to the active power source. 154 * 155 * IOKit may take many seconds to discover a built-in battery at boot time. If your user process runs 156 * at early boot, use kIOPSNotifyAttach to detect an IOPowerSource's appearance. 157 * Use notify(3) API to register for notifications. 158 */ 159#define kIOPSNotifyAttach "com.apple.system.powersources.attach" 160 161/*! 162 * @define kIOPSNotifyAnyPowerSource 163 * @abstract C-string key for a notification that of changes to any attribute of any IOPowerSource. 164 * @discussion Use notify(3) API to register for notifications. 165 * IOKit posts this notificatino more frequently than the other notifications, and thus uses more 166 * energy to run your code. To conserve CPU cycles and battery life, please consider another notification 167 * that also fits your needs. Please consider these instead: 168 * <code>@link kIOPSNotifyPowerSource @/link</code>, 169 * <code>@link kIOPSNotifyTimeRemaining @/link</code> 170 * 171 */ 172#define kIOPSNotifyAnyPowerSource "com.apple.system.powersources" 173 174/*! 175 * @constant kIOPSTimeRemainingUnknown 176 * Possible return value from <code>@link IOPSGetTimeRemainingEstimate@/link</code> 177 * Indicates the system is connected to a limited power source, but the system is still 178 * calculating a time remaining estimate. Check for a valid estimate again when IOKit posts the 179 * notification <code>@link kIOPSPowerSourcesNotificationKey@/link</code>. 180 */ 181#define kIOPSTimeRemainingUnknown ((CFTimeInterval)-1.0) 182 183/*! 184 * @constant kIOPSTimeRemainingUnlimited 185 * Possible return value from <code>@link IOPSGetTimeRemainingEstimate@/link</code> 186 * Indicates the system is connected to an external power source, without a time limit. 187 */ 188#define kIOPSTimeRemainingUnlimited ((CFTimeInterval)-2.0) 189 190/*! 191 * @function IOPSGetTimeRemainingEstimate 192 * 193 * @abstract Returns the estimated minutes remaining until all power sources 194 * (battery and/or UPS's) are empty, or returns <code>@link kIOPSTimeRemainingUnlimited@/link </code> 195 * if attached to an unlimited power source. 196 * 197 * @discussion 198 * If attached to an "Unlimited" power source, like AC power or any external source, the 199 * return value is <code>@link kIOPSTimeRemainingUnlimited@/link </code> 200 * 201 * If the system is on "Limited" power, like a battery or UPS, 202 * but is still calculating the time remaining, which may 203 * take several seconds after each system power event 204 * (e.g. waking from sleep, or unplugging AC Power), the return value is 205 * <code>@link kIOPSTimeRemainingUnknown@/link </code> 206 * 207 * Otherwise, if the system is on "Limited" power and the system has an accurate time 208 * remaining estimate, the system returns a CFTimeInterval estimate of the time 209 * remaining until the system is out of battery power. 210 * 211 * If you require more detailed battery information, use 212 * <code>@link IOPSCopyPowerSourcesInfo @/link></code> 213 * and <code>@link IOPSGetPowerSourceDescription @/link></code>. 214 * 215 * @result 216 * Returns <code>@link kIOPSTimeRemainingUnknown@/link</code> if the 217 * OS cannot determine the time remaining. 218 * 219 * Returns <code>@link kIOPSTimeRemainingUnlimited@/link</code> if the 220 * system has an unlimited power source. 221 * 222 * Otherwise returns a positive number of type CFTimeInterval, indicating the time 223 * remaining in seconds until all power sources are depleted. 224 */ 225CFTimeInterval IOPSGetTimeRemainingEstimate(void); 226 227 228/*! 229 * @functiongroup Power Source Descriptions 230 */ 231 232typedef void (*IOPowerSourceCallbackType)(void *context); 233 234/*! @function IOPSCopyPowerSourcesInfo 235 * 236 * @abstract Returns a blob of Power Source information in an opaque CFTypeRef. 237 * 238 * @discussion Clients should not directly access data in the returned CFTypeRef - 239 * they should use the accessor functions IOPSCopyPowerSourcesList and 240 * IOPSGetPowerSourceDescription, instead. 241 * 242 * @result NULL if errors were encountered, a CFTypeRef otherwise. 243 * Caller must CFRelease() the return value when done accessing it. 244 */ 245CFTypeRef IOPSCopyPowerSourcesInfo(void); 246 247/*! 248 * @function IOPSGetProvidingPowerSourceType 249 * 250 * @abstract Indicates the power source the computer is currently drawing from. 251 * 252 * @discussion Determines which power source is providing power. 253 * 254 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo(); caller may pass NULL. 255 * 256 * @result One of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey) 257 */ 258CFStringRef IOPSGetProvidingPowerSourceType(CFTypeRef snapshot); 259 260/*! @function IOPSCopyPowerSourcesList 261 * 262 * @abstract Returns a CFArray of Power Source handles, each of type CFTypeRef. 263 * 264 * @discussion The caller shouldn't directly access the CFTypeRefs, but should use 265 * IOPSGetPowerSourceDescription on each member of the CFArrayRef. 266 * 267 * @param blob Takes the CFTypeRef returned by IOPSCopyPowerSourcesInfo() 268 * 269 * @result Returns NULL if errors were encountered, otherwise a CFArray of CFTypeRefs. 270 * Caller must CFRelease() the returned CFArrayRef. 271 */ 272CFArrayRef IOPSCopyPowerSourcesList(CFTypeRef blob); 273 274/*! @function IOPSGetPowerSourceDescription 275 * 276 * @abstract Returns a CFDictionary with readable information about the specific power source. 277 * 278 * @discussion See the C-strings defined in IOPSKeys.h for specific keys into the dictionary. 279 * Don't expect all keys to be present in any dictionary. Some power sources, for example, 280 * may not support the "Time Remaining To Empty" key and it will not be present in their dictionaries. 281 * 282 * @param blob The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 283 * 284 * @param ps One of the CFTypeRefs in the CFArray returned by IOPSCopyPowerSourcesList() 285 * 286 * @result Returns NULL if an error was encountered, otherwise a CFDictionary. Caller should 287 * NOT release the returned CFDictionary - it will be released as part of the CFTypeRef returned by 288 * IOPSCopyPowerSourcesInfo(). 289 */ 290CFDictionaryRef IOPSGetPowerSourceDescription(CFTypeRef blob, CFTypeRef ps); 291 292/*! @function IOPSGetProvidingPowerSourceType 293 * 294 * @abstract Indicates the power source the computer is currently drawing from. 295 * 296 * @discussion Determines which power source is providing power. 297 * 298 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 299 * 300 * @result One of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey) 301 */ 302CFStringRef IOPSGetProvidingPowerSourceType(CFTypeRef snapshot); 303 304/*! @function IOPSNotificationCreateRunLoopSource 305 * 306 * @abstract Returns a CFRunLoopSourceRef that notifies the caller when power source 307 * information changes. 308 * 309 * @discussion Returns a CFRunLoopSourceRef for scheduling with your CFRunLoop. 310 * If your project does not use a CFRunLoop, you can alternatively 311 * receive notifications via mach port, dispatch, or signal, via <code>notify.h</code> 312 * using the name <code>@link kIOPSTimeRemainingNotificationKey @/link</code>. 313 * 314 * IOKit delivers this notification when percent remaining or time remaining changes. 315 * Thus it fires fairly frequently while discharging or charging the battery; 316 * please consider using: 317 * <code>@link IOPSCreateLimitedPowerNotification @/link</code> if you only require 318 * notifications when the power source type changes from limited to unlimited. 319 * 320 * @param callback A function to be called whenever any power source is added, removed, or changes. 321 * 322 * @param context Any user-defined pointer, passed to the IOPowerSource callback. 323 * 324 * @result Returns NULL if an error was encountered, otherwise a CFRunLoopSource. Caller must 325 * release the CFRunLoopSource. 326 */ 327CFRunLoopSourceRef IOPSNotificationCreateRunLoopSource(IOPowerSourceCallbackType callback, void *context); 328 329/*! @function IOPSCreateLimitedPowerNotification 330 * 331 * @abstract Returns a CFRunLoopSourceRef that notifies the caller when power source 332 * changes from an unlimited power source (like attached to wall, car, or airplane power), to a limited 333 * power source (like a battery or UPS). 334 * 335 * @discussion Returns a CFRunLoopSourceRef for scheduling with your CFRunLoop. 336 * If your project does not use a CFRunLoop, you can alternatively 337 * receive this notification via <code>notify.h</code> 338 * using the name <code>@link kIOPSNotifyPowerSource @/link</code> 339 * 340 * @param callback A function to be called whenever the power source changes from AC to DC.. 341 * 342 * @param context Any user-defined pointer, passed to the IOPowerSource callback. 343 * 344 * @result Returns NULL if an error was encountered, otherwise a CFRunLoopSource. Caller must 345 * release the CFRunLoopSource. 346 */ 347CFRunLoopSourceRef IOPSCreateLimitedPowerNotification(IOPowerSourceCallbackType callback, void *context) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 348 349/*! @function IOPSCopyExternalPowerAdapterDetails 350 * 351 * @abstract Returns a CFDictionary that describes the attached (AC) external 352 * power adapter (if any external power adapter is attached. 353 * 354 * @discussion Use the kIOPSPowerAdapter... keys described in IOPSKeys.h 355 * to interpret the returned CFDictionary. 356 * 357 * @result Returns a CFDictionary on success. Caller must release the returned 358 * dictionary. If no adapter is attached, or if there's an error, returns NULL. 359 */ 360CFDictionaryRef IOPSCopyExternalPowerAdapterDetails(void); 361 362__END_DECLS 363 364#endif /* _IOKIT_IOPOWERSOURCES_H */ 365