1/* 2 * Copyright (c) 2003-2010 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#ifndef _IOPowerSourcesPrivate_h_ 25#define _IOPowerSourcesPrivate_h_ 26 27#include <CoreFoundation/CoreFoundation.h> 28#include <IOKit/IOKitLib.h> 29#include <sys/cdefs.h> 30 31__BEGIN_DECLS 32 33/*! 34 * @header IOPowerSources.h 35 * @abstract Functions for interpreting power source info 36 * @discussion Provided as internal, publicly unsupported helper functions. 37 * 38 * Use with caution. 39 */ 40 41/* kIOPSReadUserVisible and kIOPSReadAll are arguments to IOPSRequestBatteryUpdate */ 42enum { 43 kIOPSReadSystemBoot = 1, 44 kIOPSReadAll = 2, 45 kIOPSReadUserVisible = 4 46}; 47 48/*! 49 * @function IOPSRequestBatteryUpdate 50 * @abstract Tell the battery driver to read the battery's state. 51 * @discussion OS X will automatically refresh user-visible battery state every 60 seconds. 52 * OS X will refresh non-user-visible battery state every 10 minutes, or less frequently. 53 * This API is primarily intended for diagnostic tools, that require more frequent 54 * updates. 55 * This call is asynchronous. This initiates a battery update, and caller should listen 56 * for a notification <code>@link kIOPSAnyPowerSourcesNotificationKey @/link</code>. 57 * @param type Pass kIOPSReadUserVisible to request user-visible data, namely 58 * time remaining & capacity. Pass kIOPSReadAll to request all battery data. 59 * @result kIOReturnSuccess on success; other IOReturn on failure. 60 */ 61IOReturn IOPSRequestBatteryUpdate(int type); 62 63 64/*! 65 * @function IOPSCopyInternalBatteriesArray 66 * @abstract Returns a CFArray of all batteries attached to the system. 67 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 68 * @result NULL if no batteriess are attached to the system. A CFArray of CFTypeRef's that 69 * reference battery descriptions. De-reference each CFTypeRef member of the array 70 * using IOPSGetPowerSourceDescription. 71 */ 72CFArrayRef IOPSCopyInternalBatteriesArray(CFTypeRef snapshot); 73 74/*! 75 * @function IOPSCopyUPSArray 76 * @abstract Returns a CFArray of all UPS's attached to the system. 77 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 78 * @result NULL if no UPS's are attached to the system. A CFArray of CFTypeRef's that 79 * reference UPS descriptions. De-reference each CFTypeRef member of the array 80 * using IOPSGetPowerSourceDescription. 81 */ 82CFArrayRef IOPSCopyUPSArray(CFTypeRef snapshot); 83 84/*! 85 * @function IOPSGetActiveBattery 86 * @abstract Returns the active battery. 87 * @discussion Call to determine the active battery on the system. On single battery 88 * systems this returns the 1 battery. On two battery systems this returns a reference 89 * to either battery. 90 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 91 * @result NULL if no batteries are present, a CFTypeRef indicating the active battery 92 * otherwise. You must dereference this CFTypeRef with IOPSGetPowerSourceDescription(). 93 */ 94CFTypeRef IOPSGetActiveBattery(CFTypeRef snapshot); 95 96/*! 97 * @function IOPSGetActiveUPS 98 * @abstract Returns the active UPS. 99 * @discussion You should call this to determine which UPS the system is connected to. 100 * This is trivial on single UPS systems, but on machines with multiple UPS's attached, 101 * it's important to track which one is actively providing power. 102 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 103 * @result NULL if no UPS's are present, a CFTypeRef indicating the active UPS otherwise. 104 * You must dereference this CFTypeRef with IOPSGetPowerSourceDescription(). 105 */ 106CFTypeRef IOPSGetActiveUPS(CFTypeRef snapshot); 107 108/*! 109 * @function IOPSPowerSourceSupported 110 * @abstract Indicates whether a power source is present on a given system. 111 * @discussion For determining if you should show UPS-specific UI 112 * @param snapshot The CFTypeRef returned by IOPSCopyPowerSourcesInfo() 113 * @param type A CFStringRef describing the type of power source (AC Power, Battery Power, UPS Power) 114 * @result kCFBooleanTrue if the power source is supported, kCFBooleanFalse otherwise. 115 */ 116CFBooleanRef IOPSPowerSourceSupported(CFTypeRef snapshot, CFStringRef type); 117 118/*! 119 * @typedef IOPSPowerSourceID 120 * @abstract An object of type IOPSPowerSourceID refers to a published power source. 121 * @discussion May be NULL. The IOPSPowerSourceID contains no visible itself; it may 122 * only be passed as an argument to IOPS API. 123 */ 124typedef struct OpaqueIOPSPowerSourceID *IOPSPowerSourceID; 125 126/*! 127 * @function IOPSCreatePowerSource 128 * @abstract Call this once per publishable power source to announce the presence of the power source. 129 * @discussion This call will not make the power source visible to the clients of IOPSCopyPowerSourcesInfo(); 130 * call IOPSSetPowerSourceDetails to share details. 131 * @param outPS Upon success, this parameter outPS will contain a reference to the new power source. 132 * This reference must be released with IOPSReleasePowerSource when (and if) the power source is no longer available 133 * as a power source to the OS. 134 * @result Returns kIOReturnSuccess on success, see IOReturn.h for possible failure codes. 135 */ 136IOReturn IOPSCreatePowerSource(IOPSPowerSourceID *outPS); 137 138/*! 139 * @function IOPSSetPowerSourceDetails 140 * @abstract Call this when a managed power source's state has substantially changed, 141 * and that state should be reflected in the OS. 142 * @discussion Generally you should not call this more than once a minute - most power sources 143 * change state so slowly that once per minute is enough to provide accurate UI. 144 * 145 * You may call this more frequently/immediately on any sudden changes in state, 146 * like sudden removal, or emergency low power warnings. 147 * 148 * @param whichPS argument is the IOPSPowerSourceID returned from IOPSCreatePowerSource(). 149 * Only the process that created this IOPSPowerSourceID may update its details. 150 * 151 * @param details Caller should populate the details dictionary with information describing the power source, 152 * using dictionary keys in IOPSKeys.h 153 * Every dictionary provided here completely replaces any prior published dictionary. 154 * 155 * @result Returns kIOReturnSuccess on success, see IOReturn.h for possible failure codes. 156 */ 157IOReturn IOPSSetPowerSourceDetails(IOPSPowerSourceID whichPS, CFDictionaryRef details); 158 159/*! 160 * @function IOPSReleasePowerSource 161 * @abstract Call this when the managed power source has been physically removed from the system, 162 * or is no longer available as a power source. 163 * 164 * @param whichPS The whichPS argument is the IOPSPowerSourceID returned from IOPSCreatePowerSource(). 165 * @result Returns kIOReturnSuccess on success, see IOReturn.h for possible failure codes. 166 */ 167IOReturn IOPSReleasePowerSource(IOPSPowerSourceID whichPS); 168 169/*! 170 * @define kIOPSNotifyPercentChange 171 * @abstract Notify(3) key. The system delivers notifications on this key when 172 * an attached power source�s percent charge remaining changes; 173 * Also delivers this notification when the active power source 174 * changes (from limited to unlimited and vice versa). 175 * 176 * @discussion See API <code>@link IOPSGetPercentRemaining @/link</code> to determine the percent charge remaining; 177 * and API <code>@link IOPSDrawingUnlimitedPower @/link</code> to determine if the active power source 178 * is unlimited. 179 * 180 * See also kIOPSNotifyPowerSource and kIOPSNotifyLowBattery 181 */ 182#define kIOPSNotifyPercentChange "com.apple.system.powersources.percent" 183 184/*! 185 * @function IOPSGetPercentRemaining 186 * @abstract Get the percent charge remaining for the device�s power source(s). 187 * @param Returns the percent charge remaining (0 to 100). 188 * @param Returns true if the power source is being charged. 189 * @param Returns true if the power source is fully charged. 190 * @result Returns kIOReturnSuccess on success, or an error code from IOReturn.h and 191 * also report the percent remaining as 100%. 192 */ 193IOReturn IOPSGetPercentRemaining(int *percent, bool *isCharging, bool *isFullyCharged); 194 195/*! 196 * @function IOPSDrawingUnlimitedPower 197 * @abstract Indicates whether the active power source is unlimited. 198 * @result Returns true if drawing from unlimited power (a wall adapter), 199 * or false if drawing from a limited source. (battery power) 200 */ 201bool IOPSDrawingUnlimitedPower(void); 202 203typedef enum { 204 kIOPSProvidedByAC = 1, 205 kIOPSProvidedByBattery, 206 kIOPSProvidedByExternalBattery 207} IOPSPowerSourceIndex; 208/*! 209 * @function IOPSGetSupportedPowerSources 210 * Returns an integer describing which power source the system is currently 211 * drawing from. 212 * Also returns true/false indicating whether the system has battery/UPS 213 * supported and/or attached. 214 * This may return an error if called very early during system boot. 215 * 216 */ 217IOReturn IOPSGetSupportedPowerSources(IOPSPowerSourceIndex *active, 218 bool *batterySupport, 219 bool *externalBatteryAttached); 220 221 222/*! 223 * These bits decipher battery state stored in notify_get_state(kIOPSTimeRemainingNotificationKey) 224 * For internal use only. 225 * Callers should use the public API IOPSGetTimeRemainingEstimate() to access this data. 226 */ 227#define kPSTimeRemainingNotifyExternalBit (1 << 16) 228#define kPSTimeRemainingNotifyChargingBit (1 << 17) 229#define kPSTimeRemainingNotifyUnknownBit (1 << 18) 230#define kPSTimeRemainingNotifyValidBit (1 << 19) 231#define kPSTimeRemainingNotifyNoPollBit (1 << 20) 232#define kPSTimeRemainingNotifyFullyChargedBit (1 << 21) 233#define kPSTimeRemainingNotifyBattSupportBit (1 << 22) 234#define kPSTimeRemainingNotifyUPSSupportBit (1 << 23) 235#if TARGET_OS_IPHONE 236#define kPSCriticalLevelBit (1 << 24) 237#define kPSRestrictedLevelBit (1 << 25) 238#endif 239#define kPSTimeRemainingNotifyActivePS8BitsStarts 56 240 241#if TARGET_OS_IPHONE 242/* 243 * Notify(3) string on which powerd posts a notification when system enters critical level 244 */ 245#define kIOPSNotifyCriticalLevel "com.apple.system.powersources.criticallevel" 246/* 247 * Notify(3) string on which powerd posts a notification when system enters restricted mode 248 */ 249#define kIOPSNotifyRestrictedMode "com.apple.system.powersources.restrictedmode" 250#endif 251 252/*! 253 * @define kIOPSBattLogEntryTime 254 * @abstract CFDictionary key used by IOPSCopyChargeLog 255 * @discussion 256 * CFDate type. Specifies the time at which an log entry is made. 257 */ 258#define kIOPSBattLogEntryTime "Log Entry Timestamp" 259 260/*! 261 * @define kIOPSBattLogEntryTZ 262 * @abstract CFDictionary key used by IOPSCopyChargeLog 263 * @discussion 264 * CFNumber type with CFNumberType set to kCFNumberDoubleType. 265 * This value specifies difference in seconds between current system 266 * time zone and GMT. Obtained with CFTimeZoneGetSecondsFromGMT(). 267 */ 268#define kIOPSBattLogEntryTZ "Log Entry Timezone" 269 270 271/* 272 *! @function IOPSCopyChargeLog 273 * 274 * @abstract Returns an array of historical battery data collected over the past 2 hours. 275 * This records a maximum of 2 hours of history at 5 minute intervals. 276 * This charge log resets upon system boot and every time this SPI is called. 277 * Caller must be signed with the 'com.apple.private.iokit.powerlogging' entitlement. 278 * It is intended for Apple internal use only. 279 * 280 * @param sinceTime IOPSCopyChargeLog will return all power source history (if any) since this date. 281 * This should be UTC based timestamp. 282 * 283 * @param chargeLog If successful, the dictionary returned will have the name of batteries as keys. A CFArray 284 * is associated with each key and this array contains log entries collected since the 285 * specified time 'sinceTime'. 286 * Each entry in this array will be a CFDictionary. 287 * Each dictionary will contain some or all of the following keys as defined in <IOKit/ps/IOPSKeys.h>. 288 * - kIOPSBattLogEntryTime - CFDate - the GMT time when the entry is recorded. 289 * - kIOPSBattLogEntryTZ - CFNumber double type. Specifies the difference in seconds 290 * between system's current time zone and GMT 291 * - kIOPSCurrentCapacityKey - mAh. A CFNumber int type. 292 * - kIOPSMaxCapacityKey - mAh. This is the Full Charge Capacity. CFNumber int type. 293 * - kIOPSPowerSourceStateKey - CFString - with string kIOPSACPowerValue or kIOPSBatteryPowerValue 294 * - kIOPSIsChargingKey - CFBoolean - is charging or not. 295 * - kIOPSIsChargedKey - CFBoolean - fully charged or not 296 * - kIOPSCurrentKey - mA. Roughly a one minute average of the battery's amperage. 297 * 298 * Upon error, or when no history is available, IOPSCopyChargeLog shall return 299 * an empty array in this parameter. 300 * 301 * @result Returns kIOReturnSuccess on success. Can return kIOReturnError or 302 * kIOReturnNotSupported on platforms with power sources. 303 */ 304IOReturn IOPSCopyChargeLog(CFAbsoluteTime sinceTime, CFDictionaryRef *chargeLog); 305 306__END_DECLS 307 308#endif 309