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