/*
* Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
*
* @APPLE_LICENSE_HEADER_START@
*
* The contents of this file constitute Original Code as defined in and
* are subject to the Apple Public Source License Version 1.1 (the
* "License"). You may not use this file except in compliance with the
* License. Please obtain a copy of the License at
* http://www.apple.com/publicsource and read it before using this file.
*
* This 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 OR NON-INFRINGEMENT. Please see the
* License for the specific language governing rights and limitations
* under the License.
*
* @APPLE_LICENSE_HEADER_END@
*/
#ifndef_IOPMLibPrivate_h_
#define_IOPMLibPrivate_h_
#include<IOKit/IOKitLib.h>
#include<CoreFoundation/CFArray.h>
#include<IOKit/pwr_mgt/IOPMLibDefs.h>
__BEGIN_DECLS
#definekIOPMServerBootstrapName"com.apple.PowerManagement.control"// AutoWake API
// For internal use communicating between IOKitUser and PM configd
// The preferences file
#definekIOPMAutoWakePrefsPath"com.apple.AutoWake.xml"// Type arguments to IOPMSchedulePowerEvent for internal use
// These types are not cancellable, nor will they appear in any lists of
// scheduled arguments from IOPMCopyScheduledEvents. These are not acceptable
// types to pass as Repeating events.
// The 'date' argument to IOPMSchedulePowerEvent is an absolute one for
// 'AutoWakeScheduleImmediate' and 'AutoPowerScheduleImmediate'. The effect
// of these WakeImmediate and PowerOnImmediate types is to schedule the
// wake/power event directly with the wake/power controller, ignoring all OS
// queueing and management. This will override a previously scheduled wake event
// by another application, should one exist. Recommended for testing only.
#definekIOPMAutoWakeScheduleImmediate"WakeImmediate"
#definekIOPMAutoPowerScheduleImmediate"PowerOnImmediate"// The 'date' argument to IOPMSchedulePowerEvent is an relative one to
// "right now," for 'AutoWakeScheduleImmediate' and 'AutoPowerScheduleImmediate'
//
// e.g. In this case, we're setting the system to wake from sleep exactly 10
// seconds after the system completes going to sleep. We're passing in a date
// 10 seconds past "right now", but the wakeup controller interprets this as
// relative to sleep time.
//
// d = CFDateCreate(0, CFAbsoluteGetCurrent() + 10.0);
// IOPMSchedulePowerEvent(d, CFSTR("SleepCycler"),
// CFSTR(kIOPMAutoWakeRelativeSeconds) );
#definekIOPMAutoWakeRelativeSeconds kIOPMSettingDebugWakeRelativeKey
#definekIOPMAutoPowerRelativeSeconds kIOPMSettingDebugPowerRelativeKey
/**************************************************
*
* Energy Saver Preferences
*
**************************************************/
#definekIOPMDynamicStoreSettingsKey"State:/IOKit/PowerManagement/CurrentSettings"
#definekIOPMDefaultPreferencesKey"Defaults"
#definekIOPMUPSPowerKey"UPS Power"
#definekIOPMBatteryPowerKey"Battery Power"
#definekIOPMACPowerKey"AC Power"// units - CFNumber in minutes
#definekIOPMDisplaySleepKey"Display Sleep Timer"// units - CFNumber in minutes
#definekIOPMDiskSleepKey"Disk Sleep Timer"// units - CFNumber in minutes
#definekIOPMSystemSleepKey"System Sleep Timer"// units - CFNumber 0/1
#definekIOPMReduceSpeedKey"Reduce Processor Speed"// units - CFNumber 0/1
#definekIOPMDynamicPowerStepKey"Dynamic Power Step"// units - CFNumber 0/1
#definekIOPMWakeOnLANKey"Wake On LAN"// units - CFNumber 0/1
#definekIOPMWakeOnRingKey"Wake On Modem Ring"// units - CFNumber 0/1
#definekIOPMRestartOnPowerLossKey"Automatic Restart On Power Loss"// units - CFNumber 0/1
#definekIOPMWakeOnACChangeKey"Wake On AC Change"// units - CFNumber 0/1
#definekIOPMSleepOnPowerButtonKey"Sleep On Power Button"// units - CFNumber 0/1
#definekIOPMWakeOnClamshellKey"Wake On Clamshell Open"// units - CFNumber 0/1
#definekIOPMReduceBrightnessKey"ReduceBrightness"// units - CFNumber 0/1
#definekIOPMDisplaySleepUsesDimKey"Display Sleep Uses Dim"// units - CFNumber 0/1
#definekIOPMMobileMotionModuleKey"Mobile Motion Module"typedefvoid (*IOPMPrefsCallbackType)(void *context);
/*!
@function IOPMPrefsNotificationCreateRunLoopSource
@abstract Returns a CFRunLoopSourceRef that notifies the caller when any PM preferences
file changes - including Energy Saver or UPS changes.
@param callback A function to be called whenever a prefs file changes.
@param context Any user-defined pointer, passed to the IOPowerSource callback.
@result Returns NULL if an error was encountered, otherwise a CFRunLoopSource. Caller must
release the CFRunLoopSource.
*/
CFRunLoopSourceRef IOPMPrefsNotificationCreateRunLoopSource(IOPMPrefsCallbackType, void *);
/*!
@function IOPMCopyPMPreferences.
@abstract Returns a CFDictionary of Power Management preferences. A preference is a CFDictionary
of Energy Saver settings. They are indexed within the dictionary by CFStrings. ("Battery Power", "AC Power")
@discussion The CFString key kIOPMDefaultPreferencesKey will be present in the top-level dictionary
if the returned value is default (as in the case of a first boot after clean install) rather
than a user-selected set of preferences.
@result Returns a CFDictionary or NULL if request failed. It's the caller's responsibility to CFRelease the dictionary.
*/
CFMutableDictionaryRef IOPMCopyPMPreferences(void);
/*!
@function IOPMSetPMPreferences.
@abstract Writes a dictionary of (name, preference) pairs back to the preferences file on disk.
Also activates these preferences and sends notifications to "interested" applications. An
application can be notified of changes to these prefs through SystemConfiguration.
@param ESPrefs Dictionary of Power Management preferences to write out to disk.
@result Returns kIOReturnSuccess or an error condition if request failed.
*/
IOReturn IOPMSetPMPreferences(CFDictionaryRef ESPrefs);
/*!
@function IOPMActivatePMPreference.
@abstract Activates the set of preferences called "name." Sets idle spin down timers and other
Energy Saver settings according to profile name.
@param SystemProfiles The dictionary of preferences from IOPMCopyPMPreferences
@param profile The name of the set of preferences defined in ESPrefs to activate.
@result Returns kIOReturnSuccess or an error condition if request failed.
*/
IOReturn IOPMActivatePMPreference(CFDictionaryRef SystemProfiles, CFStringRef profile);
/*!
@function IOPMFetaureIsAvailable
@abstract Identifies whether a PM feature is supported on this platform.
@param feature The CFSTR() feature to check availability of
@param power_source CFSTR(kIOPMACPowerKey) or CFSTR(kIOPMBatteryPowerKef). Doesn't
matter for most features, but a few are power source dependent.
@result Returns true if supported, false otherwise.
*/
bool IOPMFeatureIsAvailable(CFStringRef feature, CFStringRef power_source);
/**************************************************
*
* Dynamic Power Assertions
* Allows any application to dynamically request "Highest Performance"
*
**************************************************/// Keeps the CPU at its highest level
#definekIOPMCPUBoundAssertion CFSTR("CPUBoundAssertion")
// UNSUPPORTED: kIOPMPreventIdleSleepAssertion is UNSUPPORTED in 10.4
#definekIOPMPreventIdleSleepAssertion CFSTR("NoIdleSleepAssertion")
enum {
kIOPMAssertionDisable = 0,
kIOPMAssertionEnable = 255
};
typedefint IOPMAssertionID;
/*!
@function IOPMAssertionCreate
@abstract Dynamically requests a system behavior from the power management system.
@discussion No special privileges necessary to make this call - any process may
activate a power profile.
@param assertion The CFString profile to request from the PM system.
@param level Pass kIOPMProfileEnable or kIOPMProfileDisable.
@param assertion_id On success, a unique id will be returned in this parameter.
@result Returns kIOReturnSuccess on success, any other return indicates
PM could not successfully activate the specified profile.
*/
IOReturn IOPMAssertionCreate(CFStringRef assertion,
int level,
IOPMAssertionID *assertion_id);
/*!
@function IOPMAssertionRelease
@abstract Releases the behavior requested in IOPMAssertionCreate
@discussion All calls to IOPMAssertionCreate must be paired with calls to
IOPMAssertionRelease.
@param assertion_id The assertion_id, returned from IOPMAssertionCreate, to cancel.
@result Returns kIOReturnSuccess on success
*/
IOReturn IOPMAssertionRelease(IOPMAssertionID assertion_id);
// Use these keys to examine assertion dictionaries returned
// in IOPMCopyAssertionsByProcess() return value.
#definekIOPMAssertionTypeKey CFSTR("assert_type")
#definekIOPMAssertionValueKey CFSTR("assert_value")
/*!
@function IOPMCopyAssertionsByProcess
@abstract Returns a dictionary mapping active profiles to the processes that activated them (by pid).
@discussion Notes: One process may have multiple profiles asserted. Several processes may
have asserted the same profile to different levels.
@param assertions_by_pid On success, this returns a terribly complicated nested data structure
of assertions per process.
At the top level, keys to the CFDictionary are pids stored as CFNumbers (kCFNumberIntType).
The value associated with each CFNumber pid is a CFArray of active assertions.
Each entry in the CFArray is an assertion represented as a CFDictionary. See the keys
kIOPMAssertionTypeKey and kIOPMAssertionValueKey
@result Returns kIOReturnSuccess on success.
*/
IOReturn IOPMCopyAssertionsByProcess(CFDictionaryRef *assertions_by_pid);
/*!
@function IOPMCopyAssertionsStatus
a@bstract Returns a list of available profiles and their currently aggregated state.
@discussion Notes: One process may have multiple profiles asserted. Several processes may
have asserted the same profile to different levels.
@param assertions_status On success, this returns a CFDictionary of all profiles currently available.
The keys in the dictionary are the profile names, and the value of each is a CFNumber that
represents the aggregate level for that profile. Caller must CFRelease() this dictionary when done.
@result Returns kIOReturnSuccess on success.
*/
IOReturn IOPMCopyAssertionsStatus(CFDictionaryRef *assertions_status);
/**************************************************
*
* Power Profiles (use in combination with Energy Saver Preferences above)
*
**************************************************/
#definekIOPMCustomPowerProfile -1
#definekIOPMNumPowerProfiles 5
/*! @function IOPMCopyPowerProfilesInfo
@abstract Returns all power profiles and their corresponding Energy Settings.
@discussion The array return value contains 5 dictionaries.
- Entry 0 represents the "highest power savings", and entry 4 represents "Highest performance"
- Each entry in the array is a "Power Profile" dictionary, which in turn contains individual
dictionaries for AC Power, Battery Power, and UPS Power. Each of these per-power source
dictionaries contains a mapping of Energy Settings to their values.
Intended clients: Energy Saver Prefs, Battery Monitor, and pmset.
- Use IOPMCopyPMPreferences() to read the custom profile.
- Unsupported features and unsupported power sources will not be present in the returned data.
@result NULL on error, a CFArrayRef on success.
Caller must CFRelease() the return value when done.
*/
CFArrayRef IOPMCopyPowerProfiles(void);
/*! @function IOPMCopyActivePowerProfile
@abstract Returns the index of the currently active profile, or -1 if Custom preferences are active.
@result A CFDictionary containing 1 or more entries mapping Power Sources to the currently
selected profiles for each power source. kIOPMUPSPowerKey, kIOPMACPowerKey, kIOPMBatteryPowerKey
With corresponding CFNumber value specifying an index falling somewhere within the
IOPMCopyPowerProfiles() array
OR integer value kIOPMCustomPowerProfile.
*/
CFDictionaryRef IOPMCopyActivePowerProfiles(void);
/*! @function IOPMSetActivePowerProfile
@abstract Activates the specified power profile, or the user's custom defined profile.
@discussion Caller must have root, or admin privileges, or be the console user.
Selects and activates a system power profile per power-source.
- Use IOPMSetPMPreferences() to re-program the custom profile.
- This call triggers notifications to all clients of IOPMPrefsNotificationCreateRunLoopSource()
@param which_profile A CFDictionary specifying which profile to use for each power source.
Keys should be CFSTR: kIOPMUPSPowerKey, kIOPMACPowerKey, kIOPMBatteryPowerKey
Value should be a CFNumber (IntType) with value -1 to 4
@result kIOReturnNotPrivileged if caller does not have permission.
Caller must CFRelease() the return value when done accessing it.
*/
IOReturn IOPMSetActivePowerProfiles(CFDictionaryRef which_profile);
/**************************************************
*
* Repeating Sleep/Wake/Shutdown/Restart API
*
**************************************************/// Keys to index into CFDictionary returned by IOPSCopyRepeatingPowerEvents()
#definekIOPMRepeatingPowerOnKey"RepeatingPowerOn"
#definekIOPMRepeatingPowerOffKey"RepeatingPowerOff"
#definekIOPMAutoSleep"sleep"
#definekIOPMAutoShutdown"shutdown"// Keys to "days of week" bitfield for IOPMScheduleRepeatingPowerEvent()
enum {
kIOPMMonday = 1 << 0,
kIOPMTuesday = 1 << 1,
kIOPMWednesday = 1 << 2,
kIOPMThursday = 1 << 3,
kIOPMFriday = 1 << 4,
kIOPMSaturday = 1 << 5,
kIOPMSunday = 1 << 6
};
// Keys to index into sub-dictionaries of the dictionary returned by IOPSCopyRepeatingPowerEvents
// Absolute time to schedule power on (stored as a CFNumberRef, type = kCFNumberIntType)
//#define kIOPMPowerOnTimeKey "time"
// Bitmask of days to schedule a wakeup for (CFNumberRef, type = kCFNumberIntType)
#definekIOPMDaysOfWeekKey"weekdays"// Type of power on event (CFStringRef)
//#define kIOPMTypeOfPowerOnKey "typeofwake"
/* @function IOPMScheduleRepeatingPowerEvent
* @abstract Schedules a repeating sleep, wake, shutdown, or restart
* @discussion Private API to only be used by Energy Saver preferences panel. Note that repeating sleep & wakeup events are valid together,
* and shutdown & power on events are valid together, but you cannot mix sleep & power on, or shutdown & wakeup events.
* Every time you call IOPMSchedueRepeatingPowerEvent, we will cancel all previously scheduled repeating events of that type, and any
* scheduled repeating events of "incompatible" types, as I just described.
* @param events A CFDictionary containing two CFDictionaries at keys "RepeatingPowerOn" and "RepeatingPowerOff".
Each of those dictionaries contains keys for the type of sleep, the days_of_week, and the time_of_day. These arguments specify the
time, days, and type of power events.
* @result kIOReturnSuccess on success, kIOReturnError or kIOReturnNotPrivileged otherwise.
*/
IOReturn IOPMScheduleRepeatingPowerEvent(CFDictionaryRef events);
/* @function IOPMCopyRepeatingPowerEvents
* @abstract Gets the system
* @discussion Private API to only be used by Energy Saver preferences panel. Copies the system's current repeating power on
and power off events.
The returned CFDictionary contains two CFDictionaries at keys "RepeatingPowerOn" and "RepeatingPowerOff".
Each of those dictionaries contains keys for the type of sleep, the days_of_week, and the time_of_day.
* @result NULL on failure, CFDictionary (possibly empty) otherwise.
*/
CFDictionaryRef IOPMCopyRepeatingPowerEvents(void);
/* @function IOPMScheduleRepeatingPowerEvent
* @abstract Cancels all repeating power events
* @result kIOReturnSuccess on success, kIOReturnError or kIOReturnNotPrivileged otherwise.
*/
IOReturn IOPMCancelAllRepeatingPowerEvents(void);
__END_DECLS
#endif // _IOPMLibPrivate_h_