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 * @param       powerSourceType is the caller's type of power source, defined in IOPSKeys.h
135 * @result      Returns kIOReturnSuccess on success, see IOReturn.h for possible failure codes.
136 */
137IOReturn        IOPSCreatePowerSource(IOPSPowerSourceID *outPS, CFStringRef powerSourceType);
138
139/*!
140 *  @function   IOPSSetPowerSourceDetails
141 *  @abstract   Call this when a managed power source's state has substantially changed,
142 *              and that state should be reflected in the OS.
143 *  @discussion Generally you should not call this more than once a minute - most power sources
144 *              change state so slowly that once per minute is enough to provide accurate UI.
145 *
146 *              You may call this more frequently/immediately on any sudden changes in state,
147 *              like sudden removal, or emergency low power warnings.
148 *
149 * @param       whichPS argument is the IOPSPowerSourceID returned from IOPSCreatePowerSource().
150 *              Only the process that created this IOPSPowerSourceID may update its details.
151 *
152 * @param       details Caller should populate the details dictionary with information describing the power source,
153 *              using dictionary keys in IOPSKeys.h
154 *              Every dictionary provided here completely replaces any prior published dictionary.
155 *
156 * @result      Returns kIOReturnSuccess on success, see IOReturn.h for possible failure codes.
157 */
158IOReturn        IOPSSetPowerSourceDetails(IOPSPowerSourceID whichPS, CFDictionaryRef details);
159
160/*!
161 * @function    IOPSReleasePowerSource
162 * @abstract    Call this when the managed power source has been physically removed from the system,
163 *              or is no longer available as a power source.
164 *
165 * @param       whichPS The whichPS argument is the IOPSPowerSourceID returned from IOPSCreatePowerSource().
166 * @result      Returns kIOReturnSuccess on success, see IOReturn.h for possible failure codes.
167 */
168IOReturn        IOPSReleasePowerSource(IOPSPowerSourceID whichPS);
169
170
171/*!
172 * These bits decipher battery state stored in notify_get_state(kIOPSTimeRemainingNotificationKey)
173 * For internal use only.
174 * Callers should use the public API IOPSGetTimeRemainingEstimate() to access this data.
175 */
176#define kPSTimeRemainingNotifyExternalBit       (1 << 16)
177#define kPSTimeRemainingNotifyChargingBit       (1 << 17)
178#define kPSTimeRemainingNotifyUnknownBit        (1 << 18)
179#define kPSTimeRemainingNotifyValidBit          (1 << 19)
180#define kPSTimeRemainingNotifyNoPollBit         (1 << 20)
181
182__END_DECLS
183
184#endif
185