/* * Copyright (c) 2002 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /*! @header IOPSKeys.h IOPSKeys.h defines C strings for use accessing power source data in IOPowerSource CFDictionaries, as returned by IOPSGetPowerSourceDescription()<br> Note that all of these C strings must be converted to CFStrings before use. You can wrap them with the CFSTR() macro, or create a CFStringRef (that you must later CFRelease()) using CFStringCreateWithCString() */ #ifndef _IOPSKEYS_H_ #define _IOPSKEYS_H_ /*! @define kIOPSPowerAdapterIDKey @astract This key refers to the attached external AC power adapter's ID. The value associated with this key is a CFNumberRef intger. @discussion This key may be present in the dictionary returned from @link IOPSCopyExternalPowerAdapterDetails @/link This key might not be defined for any given power source. */ #define kIOPSPowerAdapterIDKey "AdapterID" /*! @define kIOPSPowerAdapterWattsKey @astract This key refers to the wattage of the external AC power adapter attached to a portable. The value associated with this key is a CFNumberRef integer value, in units of watts. @discussion This key may be present in the dictionary returned from @link IOPSCopyExternalPowerAdapterDetails @/link This key might not be defined for any given power source. */ #define kIOPSPowerAdapterWattsKey "Watts" /*! @define kIOPSPowerAdapterRevisionKey @abstract The power adapter's revision. The value associated with this key is a CFNumberRef integer value @discussion This key may be present in the dictionary returned from @link IOPSCopyExternalPowerAdapterDetails @/link This key might not be defined for any given power source. */ #define kIOPSPowerAdapterRevisionKey "AdapterRevision" /*! @define kIOPSPowerAdapterSerialNumberKey @abstract The power adapter's serial number. The value associated with this key is a CFNumberRef integer value @discussion This key may be present in the dictionary returned from @link IOPSCopyExternalPowerAdapterDetails @/link This key might not be defined for any given power source. */ #define kIOPSPowerAdapterSerialNumberKey "SerialNumber" /*! @define kIOPSPowerAdapterFamilyKey @abstract The power adapter's family code. The value associated with this key is a CFNumberRef integer value @discussion This key may be present in the dictionary returned from @link IOPSCopyExternalPowerAdapterDetails @/link This key might not be defined for any given power source. */ #define kIOPSPowerAdapterFamilyKey "FamilyCode" /*! */ /*! @define kIOPSUPSManagementClaimed @abstract Claims UPS management for a third-party driver. @discussion kIOPSUPSManagementClaimed Obsolete. Do not use. */ #define kIOPSUPSManagementClaimed "/IOKit/UPSPowerManagementClaimed" /*! @define kIOPSLowWarnLevelKey @abstract Key for the "Warning" UPS low power trigger-level. Default is 50%. */ #define kIOPSLowWarnLevelKey "Low Warn Level" /*! @define kIOPSDeadWarnLevelKey @abstract Key for the "Shutdown System" low power trigger-level. Default is 20%. */ #define kIOPSDeadWarnLevelKey "Shutdown Level" /*! @define kIOPSDynamicStorePath @abstract This is only used for internal bookkeeping, and should be ignored. */ #define kIOPSDynamicStorePath "/IOKit/PowerSources" /* * Power Source Commands * These keys specify UPS-specific commands. */ /*! @define kIOPSCommandDelayedRemovePowerKey @abstract Command to give a UPS when it should remove power from its AC plugs in a specified amount of time <br>The matching argumnet should be a CFNumber of kCFNumberIntType specifying when the UPS should <br>remove power from its AC power ports. */ #define kIOPSCommandDelayedRemovePowerKey "Delayed Remove Power" /*! @define kIOPSCommandEnableAudibleAlarmKey @abstract Command to give a UPS when it should either enable or disable the audible alarm. <br>The matching argumnet should be a CFBooleanRef where kCFBooleanTrue enables the alarm and <br>kCFBooleanFalse diables the alarm */ #define kIOPSCommandEnableAudibleAlarmKey "Enable Audible Alarm" /*! @define kIOPSCommandStartupDelayKey @abstract Tell UPS how long it should wait for <br>The matching argumnet should be a CFNumber of kCFNumberIntType specifying when the UPS should <br>remove power from its AC power ports. */ #define kIOPSCommandStartupDelayKey "Startup Delay" /* * Power Source data keys * These keys specify the values in a dictionary of PowerSource details. * Use these keys in conjunction with the dictionary returned by * IOPSGetPowerSourceDescription() * * Clients of IOPSCreatePowerSourceID() must specify these keys in their power source dictionaries. * Each key is labelled with one of these labels that indicate what information is required to * represent a power source in OS X. * * <br>Implementing this key is REQUIRED * <br>Implementing this key is RECOMMENDED * <br>Implementing this key is OPTIONAL. * <br>This key is DEPRECATED, do not implement it. * */ /*! @define kIOPSPowerSourceID @abstract CFNumber key uniquely identifying a UPS attached to the system. <br>OS X Power Management will specify this key. <br>Callers should not set this key; OS X will insert this key. <br>Type CFNumber, kCFNumberIntType, uniquely identifying an attached UPS. */ #define kIOPSPowerSourceIDKey "Power Source ID" /*! @define kIOPSPowerSourceStateKey @abstract CFDictionary key for the current source of power. <br>Implementing this key is REQUIRED <br> kIOPSBatteryPowerValue indicates power source is drawing internal power; kIOPSACPowerValue indicates power source is connected to an external power source. <br>Type CFString, value is kIOPSACPowerValue, kIOPSBatteryPowerValue, or kIOPSOffLineValue. */ #define kIOPSPowerSourceStateKey "Power Source State" /*! @define kIOPSCurrentCapacityKey @abstract CFDictionary key for the current power source's capacity. <br>The power source's software may specify the units for this key. The units must be consisent for all capacities reported by this power source. <br>Clients may derive a percentage of power source battery remaining by dividing "Current Capacity" by "Max Capacity" <br>Implementing this key is REQUIRED <br>Type CFNumber (signed integer) */ #define kIOPSCurrentCapacityKey "Current Capacity" /*! @define kIOPSMaxCapacityKey @abstract CFDictionary key for the current power source's maximum or "Full Charge Capacity" <br>The power source's software may specify the units for this key. The units must be consisent for all capacities reported by this power source. <br>Implementing this key is REQUIRED <br>Type CFNumber (signed integer) */ #define kIOPSMaxCapacityKey "Max Capacity" /*! @define kIOPSDesignCapacityKey @abstract CFDictionary key for the current power source's design capacity <br>The power source's software may specify the units for this key. The units must be consisent for all capacities reported by this power source. <br>Implementing this key is RECOMMENDED <br>Type CFNumber (signed integer) */ #define kIOPSDesignCapacityKey "DesignCapacity" /*! @define kIOPSTimeToEmptyKey @abstract CFDictionary key for the current power source's time remaining until empty. Only valid if the power source is running off its own power. That's when the kIOPSPowerSourceStateKey has value kIOPSBatteryPowerValue, and the value of kIOPSIsChargingKey is kCFBooleanFalse. <br>Implementing this key is RECOMMENDED <br>Type CFNumber (signed integer), units are minutes <br>A value of -1 indicates "Still Calculating the Time", otherwise estimated minutes left on the battery. */ #define kIOPSTimeToEmptyKey "Time to Empty" /*! @define kIOPSTimeToFullChargeKey @abstract CFDictionary key for the current power source's time remaining until empty. Only valid if the value of kIOPSIsChargingKey is kCFBooleanTrue. <br>Implementing this key is RECOMMENDED <br>Type CFNumber (signed integer), units are minutes <br>A value of -1 indicates "Still Calculating the Time", otherwise estimated minutes until fully charged. */ #define kIOPSTimeToFullChargeKey "Time to Full Charge" /*! @define kIOPSIsChargingKey @abstract CFDictionary key for the current power source's charging state <br>Implementing this key is REQUIRED <br>Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse */ #define kIOPSIsChargingKey "Is Charging" /*! @define kIOPSIsPresentKey @abstract CFDictionary key for the current power source's presence. <br>For instance, a PowerBook with the capacity for two batteries but with only one present would show two power source dictionaries, but kIOPSIsPresentKey would have the value kCFBooleanFalse in one of them. <br>Implementing this key is REQUIRED <br>Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse */ #define kIOPSIsPresentKey "Is Present" /*! @define kIOPSVoltageKey @abstract CFDictionary key for the current power source's electrical voltage. <br>Implementing this key is RECOMMENDED <br>Type CFNumber (signed integer) - units are mV */ #define kIOPSVoltageKey "Voltage" /*! @define kIOPSCurrentKey @abstract CFDictionary key for the current power source's electrical current. <br>Implementing this key is RECOMMENDED <br>Type CFNumber (signed integer) - units are mA */ #define kIOPSCurrentKey "Current" /*! @define kIOPSNameKey @abstract CFDictionary key for the current power source's name. <br>Implementing this key is REQUIRED <br>Type CFStringRef */ #define kIOPSNameKey "Name" /*! @define kIOPSTypeKey @abstract CFDictionary key for the type of the power source <br>Implementing this key is REQUIRED. <br>Type CFStringRef. Valid transport types are kIOPSUPSType or kIOPSInternalBatteryType. */ #define kIOPSTypeKey "Type" /*! @define kIOPSTransportTypeKey @abstract CFDictionary key for the current power source's data transport type (e.g. the means that the power source conveys power source data to the OS X machine). kIOPSInternalType describes an internal power source. kIOPSUSBTransportType, kIOPSNetworkTransportType, and kIOPSSerialTransportType usually describe UPS's. <br>Implementing this key is REQUIRED <br>Type CFStringRef. Valid transport types are kIOPSSerialTransportType, kIOPSUSBTransportType, kIOPSNetworkTransportType, kIOPSInternalType */ #define kIOPSTransportTypeKey "Transport Type" /*! @define kIOPSVendorDataKey @abstract CFDictionary key for arbitrary vendor data. <br>Implementing this key is OPTIONAL. <br>CFDictionary; contents determined by the power source software. OS X will not look at this data. */ #define kIOPSVendorDataKey "Vendor Specific Data" /*! @define kIOPSBatteryHealthKey @abstract CFDictionary key for the current power source's "health" estimate. Health indicates whether a power source is showing signs of aging, or no longer capable of providing its design charge. <br>Use value kIOPSGoodValue to describe a well-performing power source, kIOPSFairValue to describe a functional power source with limited capacity, and kIOPSPoorValue to describe a power source that's not capable of providing power. <br>Implementing this key is OPTIONAL. <br>Type CFStringRef */ #define kIOPSBatteryHealthKey "BatteryHealth" /*! @define kIOPSBatteryHealthConditionKey @abstract kIOPSBatteryHealthConditionKey broadly describes the battery's health. <br>Value is one of the "Battery Health Condition" keys described below. <br>Implementing this key is OPTIONAL - the values associated with these keys have values only used by Apple power sources. <br>Type CFStringRef */ #define kIOPSBatteryHealthConditionKey "BatteryHealthCondition" /*! @define kIOPSBatteryFailureModesKey @abstract Enumerates the specific failure modes of the battery. If detectable, various battery failures will be listed here. A battery may suffer from more than one type of failure simultaneously, as tracked in this array. If BatteryFailureModesKey is not defined (or is set to an empty dictionary), then the battery has no detectable failures. Each entry in the array should be a short descriptive string describing the error. <br>Implementing this key is RECOMMENDED <br>Type CFArrayRef */ #define kIOPSBatteryFailureModesKey "BatteryFailureModes" /*! @define kIOPSBatteryHealthConfidenceKey @abstract CFDictionary key for our confidence in the accuracy of our power source's "health" estimate. Power source does not need to define this key. <br>This key is DEPRECATED, do not implement it. <br>Type CFStringRef */ #define kIOPSHealthConfidenceKey "HealthConfidence" /*! @define kIOPSMaxErrKey @abstract CFDictionary key for the current power source's percentage error in capacity reporting. In internal batteries, this refers to the battery pack's estimated percentage error. <br>Implementing this key is OPTIONAL. <br>Type CFNumberRef, non-negative integer */ #define kIOPSMaxErrKey "MaxErr" /*! @define kIOPSIsChargedKey @abstract CFDictionary key indicates whether the battery is charged. A battery must be plugged in to an external power source in order to be fully charged. Note that a battery may validly be plugged in, not charging, and <100% charge. e.g. A battery with capacity >= 95% and not charging, is defined as charged. <br>Implementing this key is RECOMMENDED <br>Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse */ #define kIOPSIsChargedKey "Is Charged" /*! @define kIOPSIsChargedKey @abstract CFDictionary key indicates whether the battery is charged. A battery must be plugged in to an external power source in order to be fully charged. Note that a battery may validly be plugged in, not charging, and <100% charge. e.g. A battery with capacity >= 95% and not charging, is defined as charged. <br>Implementing this key is REQUIRED <br>Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse */ #define kIOPSIsChargedKey "Is Charged" /*! @define kIOPSIsFinishingChargeKey @abstract CFDictionary key indicates whether the battery is finishing off its charge. When this is true, the system UI should indicate that the battery is "Finishing Charge." Some batteries may continue charging after they report 100% capacity. <br>Implementing this key is RECOMMENDED <br>Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse */ #define kIOPSIsFinishingChargeKey "Is Finishing Charge" /*! @define kIOPSHardwareSerialNumberKey @abstract A unique serial number that identifies the power source. @discussion For Apple-manufactured batteries, this is an alphanumeric string generated during the battery manufacturing process. <br>Implementing this key is RECOMMENDED <br>Type CFStringRef */ #define kIOPSHardwareSerialNumberKey "Hardware Serial Number" /* * Transport types */ /*! @define kIOPSSerialTransportType @abstract Value for key kIOPSTransportTypeKey. Indicates the power source is a UPS attached over a serial connection. */ #define kIOPSSerialTransportType "Serial" /*! @define kIOPSUSBTransportType @abstract Value for key kIOPSTransportTypeKey. Indicates the power source is a UPS attached over a USB connection. */ #define kIOPSUSBTransportType "USB" /*! @define kIOPSNetworkTransportType @abstract Value for key kIOPSTransportTypeKey. Indicates the power source is a UPS attached over a network connection (and it may be managing several computers). */ #define kIOPSNetworkTransportType "Ethernet" /*! @define kIOPSInternalType @abstract Value for key kIOPSTransportTypeKey. Indicates the power source is an internal battery. */ #define kIOPSInternalType "Internal" /* * PS Types * A string that broadly describes the type of power source. One of these strings must be passed * as an argument to IOPSCreatePowerSource() when defining a new system power source. */ /*! * kIOPSInternalBatteryType represents a battery residing inside an Apple computer. */ #define kIOPSInternalBatteryType "InternalBattery" /*! * kIOPSUPSType represents an external attached UPS. */ #define kIOPSUPSType "UPS" /* * PS state */ /*! @define kIOPSOffLineValue @abstract Value for key kIOPSPowerSourceStateKey. Power source is off-line or no longer connected. */ #define kIOPSOffLineValue "Off Line" /*! @define kIOPSACPowerValue @abstract Value for key kIOPSPowerSourceStateKey. Power source is connected to external or AC power, and is not draining the internal battery. */ #define kIOPSACPowerValue "AC Power" /*! @define kIOPSBatteryPowerValue @abstract Value for key kIOPSPowerSourceStateKey. Power source is currently using the internal battery. */ #define kIOPSBatteryPowerValue "Battery Power" /* * Battery Health & Confidence values */ /*! @define kIOPSPoorValue @abstract Value for key kIOPSBatteryHealthKey & kIOPMPSHealthConfidenceKey. */ #define kIOPSPoorValue "Poor" /*! @define kIOPSFairValue @abstract Value for key kIOPSBatteryHealthKey & kIOPMPSHealthConfidenceKey. */ #define kIOPSFairValue "Fair" /*! @define kIOPSGoodValue @abstract Value for key kIOPSBatteryHealthKey & kIOPMPSHealthConfidenceKey. */ #define kIOPSGoodValue "Good" /* * Battery Health Condition values */ /*! @define kIOPSCheckBatteryValue @abstract Value for key kIOPSBatteryHealthConditionKey */ #define kIOPSCheckBatteryValue "Check Battery" /*! @define kIOPSPermanentFailureValue @abstract Value for key kIOPSBatteryHealthConditionKey */ #define kIOPSPermanentFailureValue "Permanent Battery Failure" /* * Battery Failure Mode values */ /*! @define kIOPSFailureExternalInput @abstract Value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureExternalInput "Externally Indicated Failure" /*! @define kIOPSFailureSafetyOverVoltage @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureSafetyOverVoltage "Safety Over-Voltage" /*! @define kIOPSFailureChargeOverTemp @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureChargeOverTemp "Charge Over-Temperature" /*! @define kIOPSFailureDischargeOverTemp @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureDischargeOverTemp "Discharge Over-Temperature" /*! @define kIOPSFailureCellImbalance @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureCellImbalance "Cell Imbalance" /*! @define kIOPSFailureChargeFET @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureChargeFET "Charge FET" /*! @define kIOPSFailureDischargeFET @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureDischargeFET "Discharge FET" /*! @define kIOPSFailureDataFlushFault @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureDataFlushFault "Data Flush Fault" /*! @define kIOPSFailurePermanentAFEComms @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailurePermanentAFEComms "Permanent AFE Comms" /*! @define kIOPSFailurePeriodicAFEComms @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailurePeriodicAFEComms "Periodic AFE Comms" /*! @define kIOPSFailureChargeOverCurrent @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureChargeOverCurrent "Charge Over-Current" /*! @define kIOPSFailureDischargeOverCurrent @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureDischargeOverCurrent "Discharge Over-Current" /*! @define kIOPSFailureOpenThermistor @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureOpenThermistor "Open Thermistor" /*! @define kIOPSFailureFuseBlown @abstract Potential value for key kIOPSBatteryFailureModesKey */ #define kIOPSFailureFuseBlown "Fuse Blown" #endif