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