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