ADC Home > Reference Library > Reference > Carbon > Resource Management > Power Manager Reference >

Next Page > Hide TOC

Power Manager Reference

Framework
CoreServices/CoreServices.h
Declared in
Power.h

Overview

The Power Manager controls power to the internal hardware devices of battery-powered Macintosh computers (such PowerBook computers). The Power Manager automatically shuts off power to internal devices to conserve power whenever the computer has not been used for a predetermined amount of time. In addition, the Power Manager allows your application or other software to

Most applications do not need to know whether they are executing on a battery-powered Macintosh computer because the transition between power states is largely invisible. As a result, most applications do not need to use Power Manager routines. You need Power Manager only if you are writing a program--such as a device driver--that must control power to some subsystem of a battery-powered Macintosh computer or that might be affected by the idle or sleep state.

Carbon supports Power Manager functions prior to Power Manager 2.0. However, many of these functions do nothing on Mac OS X; these calls have been retained in Carbon as the only means for implementing power management on Mac OS 8 and 9. Before using any of the Power Manager API, you should call the PMFeatures function to check the availability of the feature you wish to use. On Mac OS X, use the functions provided in IOKit for power management. For more information on IOKit, see I/O Kit Fundamentals.

Functions by Task

Function descriptions are grouped by the tasks for which you use the functions. For an alphabetical list of functions, go to the API index at the end of the document.

Controlling the Idle State

Controlling and Reading the Wakeup Timer

Controlling the Sleep Queue

Controlling Serial Power

Reading the Status of the Internal Modem

Reading the Status of the Battery and of the Battery Charger

Miscellaneous

Functions

BatteryCount

short BatteryCount (
   void
);

Availability
Declared In
Power.h

CurrentProcessorSpeed

Returns the current effective clock speed of the CPU in megahertz.

short CurrentProcessorSpeed (
   void
);

Return Value

The clock speed of the CPU in megahertz (MHz). One MHz represents one million cycles per second.

Special Considerations

Prior to Mac OS X 10.4, this function returns the maximum clock speed, not the current effective clock speed.

Availability
Declared In
Power.h

DisposeHDSpindownUPP

Unimplemented.

void DisposeHDSpindownUPP (
   HDSpindownUPP userUPP
);

Availability
Declared In
Power.h

DisposePMgrStateChangeUPP

Unimplemented

void DisposePMgrStateChangeUPP (
   PMgrStateChangeUPP userUPP
);

Special Considerations

The I/O Kit Framework header file IOPMLib.h (in I/O Kit Framework Reference) provides access to common power management facilites, such as initiating system sleep, getting current idle timer values, registering for sleep/wake notifications, and preventing system sleep. For additional information about power management for device drivers, see I/O Kit Fundamentals and I/O Kit Device Driver Design Guidelines.

Availability
Declared In
Power.h

DisposeSleepQUPP

void DisposeSleepQUPP (
   SleepQUPP userUPP
);

Availability
Declared In
Power.h

GetCPUSpeed

Returns the current effective clock speed of the CPU in megahertz.

long GetCPUSpeed (
   void
);

Return Value

The clock speed of the CPU in megahertz.

Discussion

For more information, see CurrentProcessorSpeed.

Availability
Declared In
Power.h

InvokeHDSpindownUPP

Unimplemented.

void InvokeHDSpindownUPP (
   HDQueueElement *theElement,
   HDSpindownUPP userUPP
);

Availability
Declared In
Power.h

InvokePMgrStateChangeUPP

Unimplemented.

void InvokePMgrStateChangeUPP (
   PMgrQueueElement *theElement,
   long stateBits,
   PMgrStateChangeUPP userUPP
);

Availability
Declared In
Power.h

InvokeSleepQUPP

long InvokeSleepQUPP (
   long message,
   SleepQRecPtr qRecPtr,
   SleepQUPP userUPP
);

Availability
Declared In
Power.h

MaximumProcessorSpeed

short MaximumProcessorSpeed (
   void
);

Version Notes

MaximumProcessorSpeed is unimplemented on versions of Mac OS X prior to Mac OS X 10.1.

Availability
Declared In
Power.h

MinimumProcessorSpeed

short MinimumProcessorSpeed (
   void
);

Special Considerations

MinimumProcessorSpeed is unimplemented on versions of Mac OS X prior to Mac OS X v10.1.

Availability
Declared In
Power.h

NewHDSpindownUPP

Unimplemented.

HDSpindownUPP NewHDSpindownUPP (
   HDSpindownProcPtr userRoutine
);

Return Value

See the description of the HDSpindownUPP data type.

Discussion

See the callback HDSpindownProcPtr for more information.

Special Considerations

The I/O Kit Framework header file IOPMLib.h (in I/O Kit Framework Reference) provides access to common power management facilites, such as initiating system sleep, getting current idle timer values, registering for sleep/wake notifications, and preventing system sleep. For additional information about power management for device drivers, see I/O Kit Fundamentals and I/O Kit Device Driver Design Guidelines.

Availability
Declared In
Power.h

NewPMgrStateChangeUPP

Unimplemented.

PMgrStateChangeUPP NewPMgrStateChangeUPP (
   PMgrStateChangeProcPtr userRoutine
);

Return Value

See the description of the PMgrStateChangeUPP data type.

Availability
Declared In
Power.h

NewSleepQUPP

SleepQUPP NewSleepQUPP (
   SleepQProcPtr userRoutine
);

Return Value

See the description of the SleepQUPP data type.

Discussion

See the callback SleepQProcPtr for more information.

Availability
Declared In
Power.h

SleepQInstall

Adds an entry to the sleep queue.

void SleepQInstall (
   SleepQRecPtr qRecPtr
);

Parameters
qRecPtr

A pointer to a sleep queue record that you must provide.

Availability
Declared In
Power.h

SleepQRemove

Removes an entry from the sleep queue.

void SleepQRemove (
   SleepQRecPtr qRecPtr
);

Parameters
qRecPtr

A pointer to a sleep queue record that you provided when you added your routine to the sleep queue.

Availability
Declared In
Power.h

UpdateSystemActivity

OSErr UpdateSystemActivity (
   UInt8 activity
);

Return Value

A result code. See “Power Manager Result Codes.”

Availability
Declared In
Power.h

Callbacks

HDSpindownProcPtr

typedef void (*HDSpindownProcPtr) (
   HDQueueElement * theElement
);

If you name your function MyHDSpindownCallback, you would declare it like this:

void MyHDSpindownCallback (
   HDQueueElement * theElement
);

Availability
Declared In
Power.h

PMgrStateChangeProcPtr

typedef void (*PMgrStateChangeProcPtr) (
   PMgrQueueElement * theElement,
   long stateBits
);

If you name your function MyPMgrStateChangeCallback, you would declare it like this:

void MyPMgrStateChangeCallback (
   PMgrQueueElement * theElement,
   long stateBits
);

Availability
Declared In
Power.h

PowerHandlerProcPtr

typedef OSStatus (*PowerHandlerProcPtr) (
   UInt32 message,
   void * param,
   UInt32 refCon,
   RegEntryID * regEntryID
);

If you name your function MyPowerHandlerCallback, you would declare it like this:

OSStatus MyPowerHandlerCallback (
   UInt32 message,
   void * param,
   UInt32 refCon,
   RegEntryID * regEntryID
);

Return Value

A result code. See “Power Manager Result Codes.”

Availability
Declared In
Power.h

SleepQProcPtr

typedef long (*SleepQProcPtr) (
   long message,
   SleepQRecPtr qRecPtr
);

If you name your function MySleepQProc, you would declare it like this:

long MySleepQProc (
   long message,
   SleepQRecPtr qRecPtr
);

Availability
Declared In
Power.h

Data Types

ActivityInfo

struct ActivityInfo {
   short ActivityType;
   unsigned long ActivityTime;
};
typedef struct ActivityInfo ActivityInfo;

Fields
ActivityType

A short representing the type of activity to fetch.

ActivityTime

An unsigned long representing the time of the last activity in ticks.

Availability
Declared In
Power.h

BatteryByte

typedef SInt8 BatteryByte;

Availability
Declared In
Power.h

BatteryInfo

struct BatteryInfo {
   UInt8 flags;
   UInt8 warningLevel;
   UInt8 reserved;
   UInt8 batteryLevel;
};
typedef struct BatteryInfo BatteryInfo;

Fields
flags

An unsigned, 8-bit integer representing battery state information.

warningLevel

An unsigned, 8-bit integer representing a scaled warning level. The value of this field is in the range of 0-255.

reserved

This field is reserved for internal use.

batteryLevel

An unsigned, 8-bit integer representing a scaled battery level. The value for this field is in the range of 0-255.

Availability
Declared In
Power.h

BatteryTimeRec

struct BatteryTimeRec {
   unsigned long expectedBatteryTime;
   unsigned long minimumBatteryTime;
   unsigned long maximumBatteryTime;
   unsigned long timeUntilCharged;
};
typedef struct BatteryTimeRec BatteryTimeRec;

Fields
expectedBatteryTime

An unsigned long representing in seconds, the estimated battery time remaining.

minimumBatteryTime

An unsigned long representing in seconds, the minimum battery time remaining.

maximumBatteryTime

An unsigned long representing in seconds, the maximum battery time remaining.

timeUntilCharged

An unsigned long representing in seconds, the time remaining until the battery is fully charged.

Availability
Declared In
Power.h

DevicePowerInfo

struct DevicePowerInfo {
   UInt32 version;
   RegEntryID regID;
   OptionBits flags;
   UInt32 minimumWakeTime;
   UInt32 sleepPowerNeeded;
};
typedef struct DevicePowerInfo DevicePowerInfo;

Fields
version

The version of this structure.

regID

The Registry Entry ID for the device.

flags

A value of type OptionBits representing device power information.

minimumWakeTime

The minimum number of seconds before the device sleeps again.

sleepPowerNeeded

The milliwatts the device requires in the sleep state.

Availability
Declared In
Power.h

HDQueueElement

struct HDQueueElement {
   struct HDQueueElement * hdQLink;
      short hdQType;
      short hdFlags;
      HDSpindownUPP hdProc;
      long hdUser;
   };
   typedef struct HDQueueElement HDQueueElement;

Fields
hdQLink

A pointer to the next queue element.

hdQType

A value of type short representing the queue element type.

hdFlags

A value of type short representing flags.

hdProc

A pointer to the hard drive spindown routine to call.

hdUser

A user-defined value.

Availability
Declared In
Power.h

HDSpindownUPP

typedef HDSpindownProcPtr HDSpindownUPP;

Availability
Declared In
Power.h

ModemByte

typedef SInt8 ModemByte;

Availability
Declared In
Power.h

PMgrQueueElement

struct PMgrQueueElement {
   struct PMgrQueueElement * pmQLink;
      short pmQType;
      short pmFlags;
      long pmNotifyBits;
      PMgrStateChangeUPP pmProc;
      long pmUser;
   };
   typedef struct PMgrQueueElement PMgrQueueElement;

Fields
pmQLink

A pointer to the next queue element.

pmQType

A value of type short representing the queue element type.

pmFlags

A value of type short representing flags.

pmNotifyBits

A bitmap representing the changes of which you wish to be notified.

pmProc

A pointer to the routine to call.

pmUser

A user-defined value.

Availability
Declared In
Power.h

PMgrStateChangeUPP

typedef PMgrStateChangeProcPtr PMgrStateChangeUPP;

Availability
Declared In
Power.h

PMResultCode

typedef long PMResultCode;

Availability
Declared In
Power.h

PowerLevel

typedef UInt32 PowerLevel;

Availability
Declared In
Power.h

PowerSourceID

typedef SInt16 PowerSourceID;

Availability
Declared In
Power.h

PowerSourceParamBlock

struct PowerSourceParamBlock {
   PowerSourceID sourceID;
   UInt16 sourceCapacityUsage;
   UInt32 sourceVersion;
   OptionBits sourceAttr;
   OptionBits sourceState;
   UInt32 currentCapacity;
   UInt32 maxCapacity;
   UInt32 timeRemaining;
   UInt32 timeToFullCharge;
   UInt32 voltage;
   SInt32 current;
   UInt32 lowWarnLevel;
   UInt32 deadWarnLevel;
   UInt32 reserved[16];
};
typedef struct PowerSourceParamBlock PowerSourceParamBlock;
typedef PowerSourceParamBlock * PowerSourceParamBlockPtr;

Fields
sourceID

A unique ID assigned by the Power Manager.

sourceCapacityUsage

An unsigned, 16-bit integer representing current capacity usage.

sourceVersion

An unsigned, 32-bit integer indicating the version of this record.

sourceAttr

A value of type OptionBits representing power source attributes.

sourceState

A value of type OptionBits representing power source states.

currentCapacity

The current capacity represented in milliwatts or percentage.

maxCapacity

The full capacity represented in milliwatts.

timeRemaining

The time remaining represented in milliwatt-hours.

timeToFullCharge

The time required to charge represented in milliwatt-hours.

voltage

The voltage represented in millivolts.

current

The current represented in milliamperes. This value may be negative if the power source is consuming.

lowWarnLevel

The low warning level represented in milliwatts, or percentage depending on the representation of sourceCapacityUsage.

deadWarnLevel

The dead warming level represented in milliwatts, or percentage depending on the representation of sourceCapacityUsage.

reserved

This field is reserved for future expansion.

Availability
Declared In
Power.h

PowerSourceParamBlockPtr

typedef PowerSourceParamBlock* PowerSourceParamBlockPtr;

Availability
Declared In
Power.h

PowerSummary

struct PowerSummary {
   UInt32 version;
   OptionBits flags;
   UInt32 sleepPowerAvailable;
   UInt32 sleepPowerNeeded;
   UInt32 minimumWakeTime;
   ItemCount deviceCount;
   DevicePowerInfo devices[1];
};
typedef struct PowerSummary PowerSummary;

Fields
version

An unsigned, 32-bit integer indicating the version of this record.

flags

A value of type OptionBits representing power summary information.

sleepPowerAvailable

An unsigned, 32-bit integer indicating the milliwatts available during sleep.

sleepPowerNeeded

An unsigned, 32-bit integer indicating the milliwatts needed during sleep.

minimumWakeTime

An unsigned, 32-bit integer indicating the minimum number of seconds required before sleeping again.

deviceCount

The number of device power info records.

devices

An array of device power info records.

Availability
Declared In
Power.h

SleepQRec

struct SleepQRec {
   SleepQRecPtr sleepQLink;
   short sleepQType;
   SleepQUPP sleepQProc;
   short sleepQFlags;
};
typedef struct SleepQRec SleepQRec;
typedef SleepQRec * SleepQRecPtr;

Fields
sleepQLink

A pointer to the next element in the queue. This pointer is maintained by the Power Manager; your application should not modify this field.

sleepQType

A short indicating the type of the queue, which must be the constant sleepQType (16).

sleepQProc

A pointer to the routine that you provide.

sleepQFlags

A short containing flags which is reserved for use by Apple Computer, Inc.

Availability
Declared In
Power.h

SleepQRecPtr

typedef SleepQRec *SleepQRecPtr;

Availability
Declared In
Power.h

SleepQUPP

typedef SleepQProcPtr SleepQUPP;

Availability
Declared In
Power.h

SoundMixerByte

typedef SInt8 SoundMixerByte;

Availability
Declared In
Power.h

StartupTime

struct StartupTime {
   unsigned long startTime;
   Boolean startEnabled;
   SInt8 filler;
};
typedef struct StartupTime StartupTime;

Availability
Declared In
Power.h

WakeupTime

struct WakeupTime {
   unsigned long wakeTime;
   Boolean wakeEnabled;
   SInt8 filler;
};
typedef struct WakeupTime WakeupTime;

Availability
Declared In
Power.h

Constants

Apple Event Types and Errors

enum {
   kAEMacPowerMgtEvt = 'pmgt',
   kAEMacToWake = 'wake',
   kAEMacLowPowerSaveData = 'pmsd',
   kAEMacEmergencySleep = 'emsl',
   kAEMacEmergencyShutdown = 'emsd'
};

BatteryByte Bits

enum {
   chargerConnBit = 0,
   hiChargeBit = 1,
   chargeOverFlowBit = 2,
   batteryDeadBit = 3,
   batteryLowBit = 4,
   connChangedBit = 5
};

Constants
chargerConnBit

When this bit is set, it indicates the charger is connected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hiChargeBit

When this bit is set, it indicates charging at fastest rate.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

chargeOverFlowBit

When this bit is set, it indicates the hicharge counter has overflowed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

batteryDeadBit

Always 0.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

batteryLowBit

When this bit is set, it indicates the battery is low.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

connChangedBit

When this bit is set, it indicates the charger connection has changed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

BatteryByte Masks

enum {
   chargerConnMask = 0x01,
   hiChargeMask = 0x02,
   chargeOverFlowMask = 0x04,
   batteryDeadMask = 0x08,
   batteryLowMask = 0x10,
   connChangedMask = 0x20
};

Constants
chargerConnMask

The charger is connected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hiChargeMask

Charging at fastest rate.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

chargeOverFlowMask

The hicharge counter has overflowed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

batteryDeadMask

The battery is dead.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

batteryLowMask

The battery is low.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

connChangedMask

The connection has changed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

BatteryInfo Bits

enum {
   batteryInstalled = 7,
   batteryCharging = 6,
   chargerConnected = 5,
   upsConnected = 4,
   upsIsPowerSource = 3
};

Constants
batteryInstalled

When this bit is set, it indicates the battery is currently connected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

batteryCharging

When this bit is set, it indicates the battery is being charged.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

chargerConnected

When this bit is set, it indicates the charger is connected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

upsConnected

When this bit is set, it indicates there is an uninterruptable power source (UPS) connected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

upsIsPowerSource

When this bit is set, it indicates the UPS is the source of power.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Client Notification Bits

enum {
   pmSleepTimeoutChanged = 0,
   pmSleepEnableChanged = 1,
   pmHardDiskTimeoutChanged = 2,
   pmHardDiskSpindownChanged = 3,
   pmDimmingTimeoutChanged = 4,
   pmDimmingEnableChanged = 5,
   pmDiskModeAddressChanged = 6,
   pmProcessorCyclingChanged = 7,
   pmProcessorSpeedChanged = 8,
   pmWakeupTimerChanged = 9,
   pmStartupTimerChanged = 10,
   pmHardDiskPowerRemovedbyUser = 11,
   pmChargeStatusChanged = 12,
   pmPowerLevelChanged = 13,
   pmWakeOnNetActivityChanged = 14
};

Client Notification Masks

enum {
   pmSleepTimeoutChangedMask = (1 << pmSleepTimeoutChanged),
   pmSleepEnableChangedMask = (1 << pmSleepEnableChanged),
   pmHardDiskTimeoutChangedMask = (1 << pmHardDiskTimeoutChanged),
   pmHardDiskSpindownChangedMask = (1 << pmHardDiskSpindownChanged),
   pmDimmingTimeoutChangedMask = (1 << pmDimmingTimeoutChanged),
   pmDimmingEnableChangedMask = (1 << pmDimmingEnableChanged),
   pmDiskModeAddressChangedMask = (1 << pmDiskModeAddressChanged),
   pmProcessorCyclingChangedMask = (1 << pmProcessorCyclingChanged),
   pmProcessorSpeedChangedMask = (1 << pmProcessorSpeedChanged),
   pmWakeupTimerChangedMask = (1 << pmWakeupTimerChanged),
   pmStartupTimerChangedMask = (1 << pmStartupTimerChanged),
   pmHardDiskPowerRemovedbyUserMask = (1 << pmHardDiskPowerRemovedbyUser),
   pmChargeStatusChangedMask = (1 << pmChargeStatusChanged),
   pmPowerLevelChangedMask = (1 << pmPowerLevelChanged),
   pmWakeOnNetActivityChangedMask = (1 << pmWakeOnNetActivityChanged)
};

DevicePowerInfo Flags

enum {
   kDevicePCIPowerOffAllowed = (1L << 0),
   kDeviceSupportsPMIS = (1L << 1),
   kDeviceCanAssertPMEDuringSleep = (1L << 2),
   kDeviceUsesCommonLogicPower = (1L << 3),
   kDeviceDriverPresent = (1L << 4),
   kDeviceDriverSupportsPowerMgt = (1L << 5)
};

Constants
kDevicePCIPowerOffAllowed

If the bit specified by this mask is set, PCI power off is allowed for this device.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceSupportsPMIS

If the bit specified by this mask is set, the device supports Power Manager Interface Specifications.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceCanAssertPMEDuringSleep

If the bit specified by this mask is set, the device can assert the PME# line during sleep.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceUsesCommonLogicPower

If the bit specified by this mask is set, the device uses common-logic power.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceDriverPresent

If the bit specified by this mask is set, the device driver is present.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceDriverSupportsPowerMgt

If the bit specified by this mask is set, the device driver installed a power handler.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

HDPwrQType Constants

enum {
   HDPwrQType = 0x4844,
   PMgrStateQType = 0x504D
};

Constants
HDPwrQType

The hard disk spindown queue element type.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

PMgrStateQType

The Power Manager state queue element type.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

HDQueueElement Flags

enum {
   kHDQueuePostBit = 0,
   kHDQueuePostMask = (1 << kHDQueuePostBit)
};

Constants
kHDQueuePostBit

When this bit is set, it indicates the routine will be called on the second pass.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kHDQueuePostMask

If the bit specified by this mask is set, it indicates the routine will be called on the second pass.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kMediaPowerCSCode Constants

enum {
   kMediaPowerCSCode = 70
};

kUseDefaultMinimumWakeTime Constants

enum {
   kUseDefaultMinimumWakeTime = 0,
   kPowerSummaryVersion = 1,
   kDevicePowerInfoVersion = 1
};

Constants
kUseDefaultMinimumWakeTime

Defaults to 5 minutes.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kPowerSummaryVersion

Version of PowerSummary structure.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDevicePowerInfoVersion

Version of DevicePowerInfo structure

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Modem State Bits

enum {
   hasInternalModem = 0,
   intModemRingDetect = 1,
   intModemOffHook = 2,
   intModemRingWakeEnb = 3,
   extModemSelected = 4,
   modemSetBit = 15
};

Constants
hasInternalModem

When this bit is set, it indicates an internal modem is installed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

intModemRingDetect

When this bit is set, it indicates the internal modem has detected a ring.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

intModemOffHook

When this bit is set, it indicates the internal modem is off the hook.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

intModemRingWakeEnb

When this bit is set, it indicates wakeup on ring is enabled.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

extModemSelected

When this bit is set, it indicates external modem is selected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

modemSetBit

When this bit is set, it indicates set bit. If 0, clear bit.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Discussion

These bits are in the bit field returned by the GetIntModemInfo function and set by the SetIntModemState function.

ModemByte Bits

enum {
   modemOnBit = 0,
   ringWakeUpBit = 2,
   modemInstalledBit = 3,
   ringDetectBit = 4,
   modemOnHookBit = 5
};

Constants
modemOnBit

When this bit is set, it indicates the modem is on.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

ringWakeUpBit

When this bit is set, it indicates ring wakeup is enabled.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

modemInstalledBit

When this bit is set, it indicates an internal modem is installed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

ringDetectBit

When this bit is set, it indicates an incoming call is detected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

modemOnHookBit

When this bit is set, it indicates the modem is off the hook.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

ModemByte Masks

enum {
   modemOnMask = 0x01,
   ringWakeUpMask = 0x04,
   modemInstalledMask = 0x08,
   ringDetectMask = 0x10,
   modemOnHookMask = 0x20
};

Constants
modemOnMask

The modem is on.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

ringWakeUpMask

Ring wakeup is enabled.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

modemInstalledMask

An internal modem is installed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

ringDetectMask

An incoming call is detected.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

modemOnHookMask

The modem is off the hook.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Net Activity Wake Options

enum {
   kConfigSupportsWakeOnNetBit = 0,
   kWakeOnNetAdminAccessesBit = 1,
   kWakeOnAllNetAccessesBit = 2,
   kUnmountServersBeforeSleepingBit = 3,
   kConfigSupportsWakeOnNetMask = (1 << kConfigSupportsWakeOnNetBit),
   kWakeOnNetAdminAccessesMask = (1 << kWakeOnNetAdminAccessesBit),
   kWakeOnAllNetAccessesMask = (1 << kWakeOnAllNetAccessesBit),
   kUnmountServersBeforeSleepingMask = (1 << kUnmountServersBeforeSleepingBit)
};

PCI Bus PMIS Power Levels

enum {
   kPMDevicePowerLevel_On = 0,
   kPMDevicePowerLevel_D1 = 1,
   kPMDevicePowerLevel_D2 = 2,
   kPMDevicePowerLevel_Off = 3
};

Constants
kPMDevicePowerLevel_On

When this bit is set, it indicates the PCI bus is fully powered.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kPMDevicePowerLevel_D1

Reserved.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kPMDevicePowerLevel_D2

Reserved.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kPMDevicePowerLevel_Off

When this bit is set, it indicates the main PCI bus power is off, but PCI standby power is available.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Power Capacity Types

enum {
   kCapacityIsActual = 0,
   kCapacityIsPercentOfMax = 1
};

Constants
kCapacityIsActual

The capacity is expressed as actual capacity in the same units as maxCapacity.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kCapacityIsPercentOfMax

The capacity is expressed as a percentage of maxCapacity.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

Power Handler Wake Results

enum {
   kDeviceDidNotWakeMachine = 0,
   kDeviceRequestsFullWake = 1,
   kDeviceRequestsWakeToDoze = 2
};

Constants
kDeviceDidNotWakeMachine

The device did not wake the computer.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceRequestsFullWake

The device did wake the computer and requests full wakeup.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kDeviceRequestsWakeToDoze

The device did wake the computer and requests partial wakeup.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Discussion

On query by the Power Manager, these are result values returned by a power handler if the device the power handler represents woke the computer.

Power Manager Features Bits

enum {
   hasWakeupTimer = 0,
   hasSharedModemPort = 1,
   hasProcessorCycling = 2,
   mustProcessorCycle = 3,
   hasReducedSpeed = 4,
   dynamicSpeedChange = 5,
   hasSCSIDiskMode = 6,
   canGetBatteryTime = 7,
   canWakeupOnRing = 8,
   hasDimmingSupport = 9,
   hasStartupTimer = 10,
   hasChargeNotification = 11,
   hasDimSuspendSupport = 12,
   hasWakeOnNetActivity = 13,
   hasWakeOnLid = 14,
   canPowerOffPCIBus = 15,
   hasDeepSleep = 16,
   hasSleep = 17,
   supportsServerModeAPIs = 18,
   supportsUPSIntegration = 19,
   hasAggressiveIdling = 20,
   supportsIdleQueue = 21
};

Constants
hasWakeupTimer

When this bit is set, it indicates the wakeup timer is supported.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasSharedModemPort

When this bit is set, it indicates the modem port is shared by the serial communications chip (SCC) and the internal modem.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasProcessorCycling

When this bit is set, it indicates processor cycling is supported.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

mustProcessorCycle

When this bit is set, it indicates processor cycling should not be turned off.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasReducedSpeed

When this bit is set, it indicates the processor can be started up at a reduced speed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

dynamicSpeedChange

When this bit is set, it indicates the processor speed can be switched dynamically.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasSCSIDiskMode

When this bit is set, it indicates SCSI disk mode is supported.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

canGetBatteryTime

When this bit is set, it indicates battery time can be calculated.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

canWakeupOnRing

When this bit is set, it indicates wakeup when the modem detects a ring.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasDimmingSupport

When this bit is set, it indicates dimming support is built in—display power management system (DPMS) standby by default.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasStartupTimer

When this bit is set, it indicates the startup timer is supported.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasChargeNotification

When this bit is set, it indicates the client can determine charge connect status change notification available.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasDimSuspendSupport

When this bit is set, it indicates support of dimming LCD and CRT to DPMS suspend state.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasWakeOnNetActivity

When this bit is set, it indicates hardware supports wake on network activity.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasWakeOnLid

When this bit is set, it indicates hardware can wake when opened.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

canPowerOffPCIBus

When this bit is set, it indicates hardware can power off PCI bus during sleep if cards allow.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasDeepSleep

When this bit is set, it indicates hardware supports deep sleep (hibernation) mode.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasSleep

When this bit is set, it indicates hardware supports normal sleep.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

supportsServerModeAPIs

When this bit is set, it indicates hardware supports server mode API.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

supportsUPSIntegration

When this bit is set, it indicates hardware supports UPS integration and reporting.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

hasAggressiveIdling

When this bit is set, it indicates Power Manager only resets OverallAct on UsrActivity.

Available in Mac OS X v10.1 and later.

Not available to 64-bit applications.

Declared in Power.h.

supportsIdleQueue

When this bit is set, it indicates Power Manager supports the idle queue.

Available in Mac OS X v10.1 and later.

Not available to 64-bit applications.

Declared in Power.h.

Discussion

These bits are in the bit field returned by the PMFeatures function.

Power Source Attribute Bits

enum {
   bSourceIsBattery = 0,
   bSourceIsAC = 1,
   bSourceCanBeCharged = 2,
   bSourceIsUPS = 3,
   bSourceProvidesWarnLevels = 4,
   kSourceIsBatteryMask = (1 << bSourceIsBattery),
   kSourceIsACMask = (1 << bSourceIsAC),
   kSourceCanBeChargedMask = (1 << bSourceCanBeCharged),
   kSourceIsUPSMask = (1 << bSourceIsUPS),
   kSourceProvidesWarnLevelsMask = (1 << bSourceProvidesWarnLevels)
};

Constants
bSourceIsBattery

When this bit is set, it indicates the power source is a battery.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

bSourceIsAC

When this bit is set, it indicates the power source is AC.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

bSourceCanBeCharged

When this bit is set, it indicates the power source can be charged.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

bSourceIsUPS

When this bit is set, it indicates the power source is an uninterruptable power supply (UPS). bSourceIsBattery and bSourceIsAC should be set as well if appropriate.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

bSourceProvidesWarnLevels

When this bit is set, it indicates power source provides low power and dead battery warning levels.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceIsBatteryMask

If the bit specified by this mask is set, the power source is a battery.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceIsACMask

If the bit specified by this mask is set, the power source is AC.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceCanBeChargedMask

If the bit specified by this mask is set, the power source can be charged.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceIsUPSMask

If the bit specified by this mask is set, the power source is a UPS.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceProvidesWarnLevelsMask

If the bit specified by this mask is set, the power source provides low power and dead battery warning levels.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

Power Source Capacity Usage Types

enum {
   kCurrentCapacityIsActualValue = 0,
   kCurrentCapacityIsPercentOfMax = 1
};

Constants
kCurrentCapacityIsActualValue

The current capacity is expressed as a real value in the same units as maxCapacity.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kCurrentCapacityIsPercentOfMax

The current capacity is expressed as a percentage of maxCapacity.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

Power Source State Bits

enum {
   bSourceIsAvailable = 0,
   bSourceIsCharging = 1,
   bChargerIsAttached = 2,
   kSourceIsAvailableMask = (1 << bSourceIsAvailable),
   kSourceIsChargingMask = (1 << bSourceIsCharging),
   kChargerIsAttachedMask = (1 << bChargerIsAttached)
};

Constants
bSourceIsAvailable

When this bit is set, it indicates a power source is installed.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

bSourceIsCharging

When this bit is set, it indicates a power source is charging.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

bChargerIsAttached

When this bit is set, it indicates a charger is connected.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceIsAvailableMask

If the bit specified by this mask is set, the power source is installed.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kSourceIsChargingMask

If the bit specified by this mask is set, the power source is charging.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

kChargerIsAttachedMask

If the bit specified by this mask is set, a charger is connected.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Power.h.

Power Source Version

enum {
   kVersionOnePowerSource = 1,
   kVersionTwoPowerSource = 2,
   kCurrentPowerSourceVersion = kVersionTwoPowerSource
};

Power Summary Flags

enum {
   kPCIPowerOffAllowed = (1L << 0)
};

Constants
kPCIPowerOffAllowed

If the bit specified by this mask is set, it indicates PCI power off is allowed.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

Sleep Commands

Not recommended

enum {
   sleepRequest = kSleepRequest,
   sleepDemand = kSleepDemand,
   sleepWakeUp = kSleepWakeUp,
   sleepRevoke = kSleepRevoke,
   sleepUnlock = kSleepUnlock,
   sleepDeny = kSleepDeny,
   sleepNow = kSleepNow,
   dozeDemand = kDozeDemand,
   dozeWakeUp = kDozeWakeUp,
   dozeRequest = kDozeRequest,
   enterStandby = kEnterStandby,
   enterRun = kEnterRun,
   suspendRequestMsg = kSuspendRequest,
   suspendDemandMsg = kSuspendDemand,
   suspendRevokeMsg = kSuspendRevoke,
   suspendWakeUpMsg = kSuspendWakeUp,
   getPowerLevel = kGetPowerLevel,
   setPowerLevel = kSetPowerLevel
};

Constants
sleepRequest

A sleep request.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

sleepDemand

A sleep demand.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

sleepWakeUp

A wakeup demand.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

sleepRevoke

A sleep request revocation.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

sleepQFlags Bits

enum {
   noCalls = 1,
   noRequest = 2,
   slpQType = 16,
   sleepQType = 16
};

Constants
noCalls

A noCalls queue type.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

noRequest

A noRequest queue type.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

slpQType

A sleepQType queue.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

sleepQType

A sleepQType queue.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

sleepQProc Commands

enum {
   kSleepRequest = 1,
   kSleepDemand = 2,
   kSleepWakeUp = 3,
   kSleepRevoke = 4,
   kSleepUnlock = 4,
   kSleepDeny = 5,
   kSleepNow = 6,
   kDozeDemand = 7,
   kDozeWakeUp = 8,
   kDozeRequest = 9,
   kEnterStandby = 10,
   kEnterRun = 11,
   kSuspendRequest = 12,
   kSuspendDemand = 13,
   kSuspendRevoke = 14,
   kSuspendWakeUp = 15,
   kGetPowerLevel = 16,
   kSetPowerLevel = 17,
   kDeviceInitiatedWake = 18,
   kWakeToDoze = 19,
   kDozeToFullWakeUp = 20,
   kGetPowerInfo = 21,
   kGetWakeOnNetInfo = 22,
   kSuspendWakeToDoze = 23,
   kEnterIdle = 24,
   kStillIdle = 25,
   kExitIdle = 26
};

Constants
kSleepDeny

A non-zero value clients can use to deny requests.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

kDozeRequest

Additional messages for Power Manager 2.0.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

kEnterStandby

Idle queue only.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

kEnterRun

Idle queue only.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

kEnterIdle

Idle queue only.

Available in Mac OS X v10.1 and later.

Declared in Power.h.

kStillIdle

Idle queue only.

Available in Mac OS X v10.1 and later.

Declared in Power.h.

kExitIdle

Idle queue only.

Available in Mac OS X v10.1 and later.

Declared in Power.h.

SoundMixerByte Bits

enum {
   MediaBaySndEnBit = 0,
   PCISndEnBit = 1,
   ZVSndEnBit = 2,
   PCCardSndEnBit = 3
};

SoundMixerByte Masks

enum {
   MediaBaySndEnMask = 0x01,
   PCISndEnMask = 0x02,
   ZVSndEnMask = 0x04,
   PCCardSndEnMask = 0x08
};

Storage Media Sleep Modes

enum {
   kMediaModeOn = 0,
   kMediaModeStandBy = 1,
   kMediaModeSuspend = 2,
   kMediaModeOff = 3
};

Constants
kMediaModeOn

When this bit is set, it indicates the media is active—the drive is spinning at full power.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kMediaModeStandBy

When this bit is set, it indicates the media is on standby. This is not implemented.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kMediaModeSuspend

When this bit is set, it indicates the media is idle. This is not implemented.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

kMediaModeOff

When this bit is set, it indicates the media is asleep—the drive is not spinning and is at minimum power and maximum recovery time.

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in Power.h.

System Activity Selectors

enum {
   OverallAct = 0,
   UsrActivity = 1,
   NetActivity = 2,
   HDActivity = 3,
   IdleActivity = 4
};

Constants
OverallAct

Delays idle sleep by a small amount. This will only delay power cycling if it's enabled, and will delay sleep by a small amount when hasAggressiveIdling is set.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

UsrActivity

Delays idle sleep and dimming by timeout time.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

NetActivity

Delays idle sleep and power cycling by small amount.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

HDActivity

Delays hard drive spindown and idle sleep by small amount.

Available in Mac OS X v10.0 and later.

Declared in Power.h.

IdleActivity

Delays idle sleep by timeout time. The IdleActivity selector is not available unless the hasAggressiveIdling bit is set. Use IdleActivity where you used to use OverallAct if necessary. Don't use IdleActivity unless hasAggressiveIdling is set; when hasAggressiveIdling is not set, the use of IdleActivity is undefined, and will do different things depending on which Power Manager is currently running.

Available in Mac OS X v10.1 and later.

Declared in Power.h.

Result Codes

The most common result codes returned by Power Manager are listed below.

Result CodeValueDescription
noErr 0

No error

Available in Mac OS X v10.0 and later.

pmBusyErr -13000

Power Manager IC stuck busy

Available in Mac OS X v10.0 and later.

pmReplyTOErr -13001

Timed out waiting to begin reply handshake

Available in Mac OS X v10.0 and later.

pmSendStartErr -13002

Power Manager IC did not start handshake

Available in Mac OS X v10.0 and later.

pmSendEndErr -13003

During send, Power Manager did not finish handshake

Available in Mac OS X v10.0 and later.

pmRecvStartErr -13004

During receive, Power Manager did not start handshake

Available in Mac OS X v10.0 and later.

pmRecvEndErr -13005

During receive, Power Manager did not finish handshake

Available in Mac OS X v10.0 and later.



Next Page > Hide TOC

© 2002, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-13)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.