-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathIOPMLibPrivate.h
3413 lines (3050 loc) · 154 KB
/
IOPMLibPrivate.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* 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@
*/
#ifndef _IOPMLibPrivate_h_
#define _IOPMLibPrivate_h_
#include <TargetConditionals.h>
#include <IOKit/IOKitLib.h>
#include <CoreFoundation/CFArray.h>
#include <IOKit/pwr_mgt/IOPMLibDefs.h>
#include <IOKit/pwr_mgt/IOPM.h>
#include <IOKit/pwr_mgt/IOPMLib.h>
#include <IOKit/ps/IOPowerSources.h>
#include <sys/cdefs.h>
__BEGIN_DECLS
/*!
* @constant kIOPBundlePath
* @abstract c-string path to powerd.bundle
*/
#define kIOPMBundlePath "/System/Library/CoreServices/powerd.bundle"
/*!
* @constant kIOPMSystemPowerStateNotify
* @abstract Notify(3) string that PM fires every time the system begins a sleep, wake, or a maintenance wake.
* @discussion The notification fires at the "system will" notificatin phase; e.g. at the beginning of the sleep or wake.
* Unless you have a strong need for this asynchronous sleep/wake notification, you
* should really be using IOPMConnectionCreate().
*/
#define kIOPMSystemPowerStateNotify "com.apple.powermanagement.systempowerstate"
/*!
* @constant kIOPMSystemPowerCapabilitiesKeySuffix
* @abstract SCDynamicStoreKey location where the system state capability can be found.
* @discussion This state is always updated immediately prior to when PM delivers
* the notify (3) notification kIOPMSystemPowerStateNotify
* The System power capabilities are defined by the
* enum <code>@link IOPMCapabilityBits@/link</code> below.
*/
#define kIOPMSystemPowerCapabilitiesKeySuffix "/IOKit/SystemPowerCapabilities"
/*! @define kIOUserActivityNotifyName
@abstract The notification by this name fires when User activity state on the system changes.
@discussion Pass this string as an argument to register via notify(3).
You can query User activity state via notify_get_state() when this notification
fires. The returned value will be either kIOUserIsIdle or kIOUserIsActive
*/
enum {
kIOUserIsIdle = 0,
kIOUserIsActive = 1
};
#define kIOUserActivityNotifyName "com.apple.system.powermanagement.useractivity"
/*! @define kIOUserAssertionReSync
@abstract This is the Notify(3) string fired by powerd every time the process is started.
*/
#define kIOUserAssertionReSync "com.apple.system.powermanagement.assertionresync"
/*! @define kIOPMDarkWakeControlEntitlement
* @abstract Apple internal entitlement for processes that may influence
* DarkWake policy.
*/
#define kIOPMDarkWakeControlEntitlement CFSTR("com.apple.private.iokit.darkwake-control")
/*! @define kIOPMDarkWakeControlEntitlement
* @abstract Apple internal entitlement for processes that receive Interactive Push notifications.
*/
#define kIOPMInteractivePushEntitlement CFSTR("com.apple.private.iokit.interactive-push")
/*! @define kIOPMReservePwrCtrlEntitlement
* @abstract Apple internal entitlement for processes that create kIOPMAssertAwakeReservePower assertion
* and call IOPMSetReservePowerMode()
*/
#define kIOPMReservePwrCtrlEntitlement CFSTR("com.apple.private.iokit.reservepower-control")
/*!
* @constant kIOPMServerBootstrapName
* @abstract Do not use. There's no reason for any code outside of PowerManagement to use this.
* @discussion The PM system server registers via this key with launchd.
*/
#define kIOPMServerBootstrapName "com.apple.PowerManagement.control"
/*!
* @group AutoWake API
* @abstract For internal use communicating between IOKitUser and PM configd
*/
/*!
* @constant kIOPMAutoWakePresPath
* @abstract Filename of the scheduled power events file.
*/
#define kIOPMAutoWakePrefsPath "com.apple.AutoWake.xml"
/*
* @constant kIOPMAutoWakeScheduleImmediate
* @abstract Internal only argument to <code>@link IOPMSchedulePowerEvent@/link</code>
* for use only by debugging tools.
* @discussion Once scheduled, 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.
*/
#define kIOPMAutoWakeScheduleImmediate "WakeImmediate"
/*
* @constant kIOPMAutoPowerScheduleImmediate
* @abstract Internal only argument to <code>@link IOPMSchedulePowerEvent@/link</code>
* for use only by debugging tools.
* @discussion Once scheduled, 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.
*
*
*/
#define kIOPMAutoPowerScheduleImmediate "PowerOnImmediate"
/*!
* @constant kIOPMSchedulePowerEventNotification
* @abstract Notification posted when IOPMSchedulePowerEvent successfully schedules a power event
* @discussion i.e. this notify(3) notification fires every time the list of scheduled power events changes.
*/
#define kIOPMSchedulePowerEventNotification "com.apple.system.IOPMSchedulePowerEventNotification"
/*!
* @constant kIOPMUserVisiblePowerEventNotification
* @abstract Notification posted when IOPMSchedulePowerEvent or IOPMCancelScheduledPowerEvent is called
* for a UserVisible event
* @discussion i.e. this notify(3) notification fires every time the list of scheduled power events changes.
*/
#define kIOPMUserVisiblePowerEventNotification "com.apple.system.powermanagement.uservisiblepowerevent"
/*
* @constant kIOPMAutoWakeRelativeSeconds
* @abstract Internal only argument to <code>@link IOPMSchedulePowerEvent@/link</code>
* for use only by debugging tools.
* @discussion The 'date' argument to IOPMSchedulePowerEvent is an relative one to "right now,"
* when passing type for 'kIOPMSettingDebugWakeRelativeKey' or 'kIOPMAutoPowerRelativeSeconds'
*
* 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) );
*/
#define kIOPMAutoWakeRelativeSeconds kIOPMSettingDebugWakeRelativeKey
/*
* @constant kIOPMAutoPowerRelativeSeconds
* @abstract Internal only argument to <code>@link IOPMSchedulePowerEvent@/link</code>
* for use only by debugging tools.
* @discussion The 'date' argument to IOPMSchedulePowerEvent is an relative one to "right now,"
* when passing type for 'kIOPMSettingDebugWakeRelativeKey' or 'kIOPMAutoPowerRelativeSeconds'
*
* 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) );
*/
#define kIOPMAutoPowerRelativeSeconds kIOPMSettingDebugPowerRelativeKey
/**************************************************
*
* Repeating Sleep/Wake/Shutdown/Restart API
*
**************************************************/
/*!
* @functiongroup Repeating power events
*/
// Keys to index into CFDictionary returned by IOPSCopyRepeatingPowerEvents()
#define kIOPMRepeatingPowerOnKey "RepeatingPowerOn"
#define kIOPMRepeatingPowerOffKey "RepeatingPowerOff"
#define kIOPMAutoSleep "sleep"
#define kIOPMAutoShutdown "shutdown"
#define kIOPMPowerEventLeewayKey "leeway"
#define kIOPMPowerEventUserVisible "UserVisible"
// 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)
#define kIOPMDaysOfWeekKey "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);
/*!
* @function IOPMRequestSysWake
*
* @abstract Requests the system to wake up from sleep at the specified time
* @param request Dictionary describing the wake request
*
* @discussion
* Request device to wake up at the specified time.
*
* kIOPMPowerEventAppNameKey CFStringRef, mandatory. Specifies the purpose of this wake and used for logging and debugging
* kIOPMPowerEventTimeKey CFDateRef, mandatory. Specifies the time when system has to wake up.
* kIOPMPowerEventLeewayKey CFNumber(kCFNumberIntType), optional. Specifies the number of seconds by which wake can be delayed
* to coalesce with other wake requests. Defaults to 0.
* kIOPMPowerEventUserVisible CFBooleanRef, optional. Specifies if the RTC wake request will be visible to
* user(Clock alarm, Mail Alert etc)
*/
IOReturn IOPMRequestSysWake(CFDictionaryRef request);
#pragma mark Private Assertions
/**************************************************
*
* Private assertions
*
**************************************************/
/*!
* @group Private Assertions
*/
/*!
* @constant kIOPMAssertionTypeApplePushServiceTask
*
* @discussion When active during a SleepServices wake, will keep the system awake, subject to
* the sleep services time cap.
*
* Except for running during SleepServices time, while a system is on battery power
* a ApplePushServiceTask assertion cannot keep the machine in a higher power state.
* e.g. An ApplePushServiceTask cannot prevent sleep if the system is on battery.
*
* Awake Behavior on AC power: this assertion has no effect during full wake.
*
* DarkWake Behavior on AC power: this assertion will force the system not to sleep;
* e.g. the system will stay in DarkWake as long as this assertion is held.
*
* If the platform supports SilentRunning, the assertion shall implement
* this behavior:
* - Keeps the system awake during DarkWake.
* - Valid on AC & Battery
* - Only valid in DarkWake
* - Only valid during global SleepServicesTimeout Window (as determined by powerd)
* - Only valid while SMC is in SilentRunning mode
*
* If the platform doesn't support SilentRunning, the assertion shall
* implement this behavior:
* - Prevents idle sleep
* - Valid on AC & Battery
* - Only valid in FullWake
* - Only valid during global SleepServicesTimeout Window (as determined by powerd)
* For SilentRunning support, see:
* - <code>IOPMFeatureIsSupported(CFSTR(kIOPMSilentRunningKey))</code>
*/
#define kIOPMAssertionTypeApplePushServiceTask CFSTR("ApplePushServiceTask")
/*!
* @constant kIOPMAssertInteractivePushServiceTask
*
* @abstract Push Service infrastructure apps must take this while processing a push
* and hold it until they can determine whether that push will cause
* a user interactive wake or NotificationWake.
*
* @discussion Since pushes might or might not cause a user interactive wake, OS X needs
* to wait until the recipient App can decide whether they do. Thus apsd and
* apps must hold this assertion while they process incoming pushes.
*
* The caller must hold the darkwake-control entitlement:
* - kIOPMDarkWakeControlEntitlement
*
* If system supports TCPKeepAlive, and TCPKeepAlive is dynamically enabled,
* the assertion shall implement the following behavior:
* - Prevents idle sleep
* - Prevents forced sleep
* - Reverts sleeps in progress.
* - Valid on AC & Battery
* - Valid in DarkWake & FullWake
* - Per-assertion timeout (specified by IOPPF)
* - OS X will prefer to run fanless; but OS X shall allow
* the fans to come on. That is, OS X prefer that processes run
* to completion over avoiding fan noise.
*
* If the system does not support TCPKeepAlive, or TCPKeepAlive is dynamically
* disabled, then this assertion shall implement
* kIOPMAssertionTypeApplePushServiceTask behavior.
*/
#define kIOPMAssertInteractivePushServiceTask CFSTR("InteractivePushServiceTask")
/*!
* @constant kIOPMAssertionTypeBackgroundTask
*
* @discussion This assertion should be created and held by applications while performing
* system maintenance tasks, e.g. work not initiated by a user.
*
* Only Centralized Task Scheduler Power Nap processes should use this assertion.
*
* Example: Periodic system data backups, spotlight indexing etc.
*
* Behavior of this assertion on Systems that support Silent Running:
* On AC: Prevents sytem sleep. If system is idle or if user requests sleep(by
* lid close or by selecting sleep from apple menu), system runs with display
* off in silent running mode. Holding this assertion during darkwake results
* in extending dark wake in silent running mode.
* On Battery: This assertion is not honoured.
*
* Behavior on Systems that don't support Silent Running:
* On AC: Prevents system idle sleep. Display may get turned off. If user requests
* sleep(by lid close or apple menu sleep), then system goes into sleep.
* If the assertion is held during dark wake, it is not honored.
* On Battery: This assertion is not honoured.
*
*/
#define kIOPMAssertionTypeBackgroundTask CFSTR("BackgroundTask")
/*!
* @constant kIOPMAssertAwakeReservePower
*
* @discussion This assertion should be created to prevent system idle sleep even when system
* is in reserve power mode.
*
* Process creating this assertion must have kIOPMReservePwrCtrlEntitlement
* entitlement.
*/
#define kIOPMAssertAwakeReservePower CFSTR("AwakeOnReservePower")
/*! @define kIOPMAssertionTypeDenySystemSleep
* @deprecated Please use public assertion <code>@link kIOPMAssertionTypePreventSystemSleep@/link</code>,
* instead of this one.
*/
#define kIOPMAssertionTypeDenySystemSleep CFSTR("DenySystemSleep")
/*! @define kIOPMAssertionUserIsActive
* @abstract Powers on the display and prevents display from going dark.
* @discussion This is the backend assertion supporting
* <code>@link IOPMAssertionDeclareUserActivity @/link</code>.
*
* Public API users should call IOPMAssertionDeclareUserActivity;
* internal Apple SPI users may opt to directly create this assertion
* for finer grained control over its timeout.
*/
#define kIOPMAssertionUserIsActive CFSTR("UserIsActive")
/*! @define kIOPMAssertDisplayWake
* @abstract For IOKit use only.
* This is the acking assertion for:
* <code>@link IOPMAssertionDeclareNotificationEvent@/link</code>
* @discussion Don't create this assertion directly. Always take it by
* calling IOPMAssertionDeclareNotificationEvent.
* Callers must be entitled with com.apple.private.iokit.darkwake-control
* to use this assertion or to call IOPMAssertionDeclareNotificationEVent.
*/
#define kIOPMAssertDisplayWake CFSTR("DisplayWake")
/*! @define kIOPMAssertInternalPreventSleep
* @abstract For powerd use only.
* @discussion Assertion taken by powerd as a proxy temporarily.
* This can be taken either to finish a short-term task(like device enumeration)
* or to keep system awake until wake reason is detected and the apps specific to this
* wake take their own assertion.
* Do not use this assertion outside of powerd.
*/
#define kIOPMAssertInternalPreventSleep CFSTR("InternalPreventSleep")
/*! @define kIOPMAssertiInternalPreventDisplaySleep
* @abstract For powerd use only.
* @discussion Assertion taken by powerd as a proxy temporarily to prevent display sleep.
* Do not use this assertion outside of powerd.
*/
#define kIOPMAssertInternalPreventDisplaySleep CFSTR("InternalPreventDisplaySleep")
/*! @define kIOPMAssertRequiresDisplayAudio
*
* @discussion Prevents display from sleeping even if user is idle, but allows loginwindow
* to start the screen saver.
*/
#define kIOPMAssertRequiresDisplayAudio CFSTR("RequiresDisplayAudio")
/*! @define kIOPMAssertMaintenanceActivity
*
* @abstract Keep the system awake in FullWake or DarkWake for maintenance activity.
* AC/Batt behavior - Works on AC only
* Acoustics behavior - This assertion will not trigger system to
* go into non-silent running mode.
*/
#define kIOPMAssertMaintenanceActivity CFSTR("MaintenanceWake")
/* @define kIOPMAssertionTypeSystemIsActive
* @abstract Prevents idle sleep, but also reverts a sleep-in-progress.
*
* @discussion Do not create this assertion directly. Create it by calling
* <code>@link IOPMAssertionDeclareSystemActivity()@/link</code>
*
* 'kIOPMAssertionTypeSystemIsActive will revert an idle sleep currently in progress
* where possible. If reverting an idle sleep is not possible, it will try to wake the system
* up immediately once the system goes to sleep. Apart from this one side-effect, it behaves
* identically to a PreventUserIdleSystemSleep assertion.
*
* Consider calling IOPMAssertionDeclareSystemActivity() if you would like to create an
* assertion of this type instead of directly creating it using one of the IOPMAssertionCreate
* APIs.
*
*/
#define kIOPMAssertionTypeSystemIsActive CFSTR("SystemIsActive")
// Disables AC Power Inflow (requires root to initiate)
#define kIOPMAssertionTypeDisableInflow CFSTR("DisableInflow")
#define kIOPMInflowDisableAssertion kIOPMAssertionTypeDisableInflow
// Disables battery charging (requires root to initiate)
#define kIOPMAssertionTypeInhibitCharging CFSTR("ChargeInhibit")
#define kIOPMChargeInhibitAssertion kIOPMAssertionTypeInhibitCharging
// Disables low power battery warnings
#define kIOPMAssertionTypeDisableLowBatteryWarnings CFSTR("DisableLowPowerBatteryWarnings")
#define kIOPMDisableLowBatteryWarningsAssertion kIOPMAssertionTypeDisableLowBatteryWarnings
// Once initially asserted, the machine may only idle sleep while this assertion
// is asserted. For embedded use only.
#define kIOPMAssertionTypeEnableIdleSleep CFSTR("EnableIdleSleep")
// Needs CPU Assertions - DEPRECATED
// Only have meaning on PowerPC machines.
#define kIOPMAssertionTypeNeedsCPU CFSTR("CPUBoundAssertion")
#define kIOPMCPUBoundAssertion kIOPMAssertionTypeNeedsCPU
// Assertion Actions
#define kPMASLAssertionActionCreate "Created"
#define kPMASLAssertionActionRetain "Retain"
#define kPMASLAssertionActionRelease "Released"
#define kPMASLAssertionActionClientDeath "ClientDied"
#define kPMASLAssertionActionTimeOut "TimedOut"
#define kPMASLAssertionActionSummary "Summary"
#define kPMASLAssertionActionTurnOff "TurnedOff"
#define kPMASLAssertionActionTurnOn "TurnedOn"
#define kPMASlAssertionActionCapTimeOut "CapExpired"
#define kPMASLAssertionActionNameChange "NameChange"
#pragma mark Private Assertion Dictionary Keys
/*
* Private Assertion Dictionary Keys
*/
#define kIOPMAssertionUsedDeprecatedCreateAPIKey CFSTR("UsedDeprecatedCreateAPI")
/*! @constant kIOPMAssertionCreateDateKey
* @abstract Records the time at which the assertion was created.
*/
#define kIOPMAssertionCreateDateKey CFSTR("AssertStartWhen")
/*! @constant kIOPMAssertionReleaseDateKey
* @abstract Records the time that the assertion was released.
* @discussion The catch is that we only record the release time for assertions that have
* already timed out. In the normal create/release lifecycle of an assertion, we won't record
* the release time because we'll destroy the assertion object upon its release.
*/
#define kIOPMAssertionReleaseDateKey CFSTR("AssertReleaseWhen")
/*! @constant kIOPMAssertionTimedOutDateKey
* @abstract Records the time that an assertion timed out.
* @discussion An assertion times out when its specified timeout interval has elapsed.
* This value only exists once the assertion has timedout. The presence of this
* key/value pair in a dictionary indicates the assertion has timed-out.
*/
#define kIOPMAssertionTimedOutDateKey CFSTR("AssertTimedOutWhen")
/*! @constant kIOPMAssertionTimeOutIntervalKey
* @abstract The owner-specified timeout for this assertion.
*/
#define kIOPMAssertionTimeOutIntervalKey CFSTR("AssertTimeOutInterval")
/*! @constant kIOPMAssertionTimeoutTimeLeftKey
* @abstract Records number of seconds left before this assertion times out
*/
#define kIOPMAssertionTimeoutTimeLeftKey CFSTR("AssertTimeoutTimeLeft")
/*! @constant kIOPMAssertionTimeoutUpdateTimeKey
* @abstract Records the time at which 'kIOPMAssertionTimeoutTimeLeftKey' is updated
*/
#define kIOPMAssertionTimeoutUpdateTimeKey CFSTR("AssertTimeoutUpdateTime")
/*! @constant kIOPMAssertionPIDKey
* @abstract The owning process's PID.
*/
#define kIOPMAssertionPIDKey CFSTR("AssertPID")
/*! @constant kIOPMAssertionGlobalIDKey
* @abstract A uint64_t integer that can uniuely identify an assertion system-wide.
*
* @discussion kIOPMAssertionGlobalIDKey differs from the assertion ID (of type IOPMAssertionID)
* returned by IOPMAssertionCreate* API. kIOPMAssertionGlobalIDKey can refer to
* an assertion owned by any process. The 32-bit IOPMAssertionID only refers to
* assertions within the process that created the assertion.
* You can use the API <code>@link IOPMCopyAssertionsByProcess@/link</code>
* to see assertion data for all processes.
*/
#define kIOPMAssertionGlobalUniqueIDKey CFSTR("GlobalUniqueID")
/*!
* @define kIOPMAssertionAppliesToLimitedPowerKey
*
* @abstract The CFDictionary key for assertion power limits in an assertion info dictionary.
*
* @discussion The value for this key will be a CFBooleanRef, with value
* <code>kCFBooleanTrue</code> or <code>kCFBooleanFalse</code>. A value of
* kCFBooleanTrue means that the assertion is applied even when system is running
* on limited power source like battery. A value of kCFBooleanFalse means that
* the assertion is applied only when the system is running on unlimited power
* source like AC.
*
* This property is valid only for assertion <code>@link kIOPMAssertionTypePreventSystemSleep @/link</code>.
* By default, this assertion is applied only when system is running on unlimited
* power source. This behavior can be changed using this property.
*/
#define kIOPMAssertionAppliesToLimitedPowerKey CFSTR("AppliesToLimitedPower")
/*!
* @define kIOPMAssertionAppliesOnLidClose
*
* @abstract The CFDictionary key in assertion info dictionarty for enabling assertion when lid is closed.
*
* @discussion The value for this key will be a CFBooleanRef, with value
* <code>kCFBooleanTrue</code> or <code>kCFBooleanFalse</code>. A value of
* kCFBooleanTrue means that the assertion is applied even when lid is closed.
* A value of kCFBooleanFalse means that the assertion is applied only when
* lid is open.
*
* This property is valid only for assertion <code>@link kIOPMAssertionUserIsActive @/link</code>.
* By default, this assertion is applied only when lid is open and setting this assertion property
* changes that default behavior. This assertion property has no meaning on systems with no lid
* and it is treated as no-op.
*/
#define kIOPMAssertionAppliesOnLidClose CFSTR("AppliesOnLidClose")
/*!
* @define kIOPMAssertionAutoTimesout
*
* @abstract The CFDictionary key in assertion info dictionary for auto timing out assertion after pre-defined
* number of seconds.
*
* @discussion The value for this key will be a CFBooleanRef, with value <code>kCFBooleanTrue</code> or
* <code>kCFBooleanFalse</code>. A value of kCFBooleanTrue means that the assertion is allowed
* to auto-timeout after pre-defined number of seconds. The auto-timeout duration is a fixed value
* for all assertions with this property.
*
* A value of kCFBooleanFalse means that the auto-timeout is not allowed.
* This is the default value when this key is not set.
*
* This optional property can be set at the time of assertion creation and
* cannot be changed later.
*/
#define kIOPMAssertionAutoTimesout CFSTR("AutoTimesout")
/*!
* @define kIOPMAssertionResourcesUsed
*
* @abstract This CFDictionary key in assertion info dictionary lists the resources used
* by the process creating this assertion, or by the process on-behalf of which
* this assertion is created.
*
* @discussion The value for this key will be a CFArray, with each element specifying the
* resource used by the process.
*
* This optional property can be changed after the property is created.
*/
#define kIOPMAssertionResourcesUsed CFSTR("ResourcesUsed")
/*
* Resource strings that can be used with kIOPMAssertionResourcesUsed key.
*/
#define kIOPMAssertionResourceAudioIn CFSTR("audio-in")
#define kIOPMAssertionResourceAudioOut CFSTR("audio-out")
#define kIOPMAssertionResourceGPS CFSTR("GPS")
#define kIOPMAssertionResourceBaseband CFSTR("baseband")
#define kIOPMAssertionResourceBluetooth CFSTR("bluetooth")
/*!
* @define kIOPMAssertionResourcesName
*
* @abstract This CFDictionary key in assertion info dictionary lists the specific name
* of the resource used. If this key is set, then kIOPMAssertionResourcesUsed
* key should also be set. The resource names may be used to look up to registry.
*
* @discussion The value for this key will be a CFArray, with each element specifying the
* resource names.
*
* This optional property can be changed after the property is created.
*/
#define kIOPMAssertionResourcesName CFSTR("ResourcesName")
/*!
* @define kIOPMAssertionActivityBudgeted
*
* @abstract The CFDictionary key in assertion info dictionary specifies if the activity
* for which the assertion is created is budgeted.
*
* @discussion The value for this key will be a CFBooleanRef, with value <code>kCFBooleanTrue</code> or
* <code>kCFBooleanFalse</code>. A value of kCFBooleanTrue means that the activity
* for which the assertions is created is budgeted.
*
* A value of kCFBooleanFalse means that the acitivity is not budgeted.
* This is the default value when this key is not set.
*
* This optional property can be set at the time of assertion creation and
* cannot be changed later. Only the activity scheduler is expected to set this property.
*/
#define kIOPMAssertionActivityBudgeted CFSTR("ActivityBudgeted")
/*!
* @define kIOPMAssertionAllowsDeviceRestart
*
* @abstract The CFDictionary key in assertion info dictionary to specify that it is ok to
* restart the device even when this assertion is active.
*
* @discussion The value for this key will be a CFBooleanRef, with value <code>kCFBooleanTrue</code> or
* <code>kCFBooleanFalse</code>. A value of kCFBooleanTrue means that the system can be
* restarted for system maintenance even when the assertion is active.
*
* A value of kCFBooleanFalse means that the system should NOT be restarted.
* This is the default value when this key is not set.
*
* This optional property can be set at the time of assertion creation and
* cannot be changed later.
*/
#define kIOPMAssertionAllowsDeviceRestart CFSTR("AllowsDeviceRestart")
/*!
* @constant kIOPMAssertionCreatorBacktrace
* @abstract CFDataRef type. If present, holds the backtrace of the thread creating assertion.
*/
#define kIOPMAssertionCreatorBacktrace CFSTR("CreatorBacktrace")
/*!
* @constant kIOPMAssertionOnBehalfOfPID
* @abstract CFNumberRef type. If present, specifies the PID on whose behalf the assertion is created.
* This can be different from 'kIOPMAssertionPIDKey' as one process can be creating assertion for
* other process. This key is purely for accounting & debugging purpose and no action is taken
* when 'kIOPMAssertionOnBehalfOfPID' dies.
* This optional property can be set only at the time assertion creation and shouldn't be
* changed after assertion is created.
*/
#define kIOPMAssertionOnBehalfOfPID CFSTR("AssertionOnBehalfOfPID")
/*!
* @constant kIOPMAssertionOnBehalfOfPIDReason
* @abstarct CFStringRef type. If present, gives a description on why process with PID 'kIOPMAssertionPIDKey' is
* creating assertion on behalf of process with PID 'kIOPMAssertionOnBehalfOfPID'
* This optional property can be set only at the time assertion creation and shouldn't be
* changed after assertion is created.
*/
#define kIOPMAssertionOnBehalfOfPIDReason CFSTR("AssertionOnBehalfOfPIDReason")
/*!
* @constant kIOPMAssertionOnBehalfOfBundleID
* @abstract CFStringRef type. If present, specifies the Bundle ID on whose behalf the assertion is created.
* This optional property can be set only at the time assertion creation and shouldn't be
* changed after assertion is created.
*/
#define kIOPMAssertionOnBehalfOfBundleID CFSTR("AssertionOnBehalfOfBundleID")
/*!
* @constant kIOPMAssertionTrueTypeKey
* @abstract Shows the current supported assertion name for the deprecated name
*/
#define kIOPMAssertionTrueTypeKey CFSTR("AssertionTrueType")
/*!
* @constant kIOPMAssertionIdKey
* @abstract Holds the assertionId returned to client on creation
*/
#define kIOPMAssertionIdKey CFSTR("AssertionId")
/*!
* @constant kIOPMAsyncClientAssertionIdKey
* @abstract Holds the assertionId returned to client on creation
*/
#define kIOPMAsyncClientAssertionIdKey CFSTR("AsyncClientAssertionId")
/*!
* @constant kIOPMAssertionTimedOutNotifyString
* @discussion Assertion notify(3) string
* Fires when an assertion times out. Caller has to call IOPMAssertionNotify()
* and register with powerd with this string before calling notify_register.
*/
#define kIOPMAssertionTimedOutNotifyString "com.apple.system.powermanagement.assertions.timeout"
/*!
* @constant kIOPMAssertionsAnyChangedNotifyString
* @discussion Assertion notify(3) string
* Fires when any individual assertion is created, released, or modified.
* Caller has to call IOPMAssertionNotify() and register with powerd
* with this string before calling notify_register.
*
*/
#define kIOPMAssertionsAnyChangedNotifyString "com.apple.system.powermanagement.assertions.anychange"
/*!
* @constant kIOPMAssertionsChangedNotifyString
* @discussion Assertion notify(3) string
* Fires when global assertion levels change. This notification
* doesn't necessarily fire when any individual assertion is
* created, released, or modified.
* Caller has to call IOPMAssertionNotify() and register with powerd
* with this string before calling notify_register.
*/
#define kIOPMAssertionsChangedNotifyString "com.apple.system.powermanagement.assertions"
/*!
* @constant kIOPMAssertionsCollectBTString
* @discussion Assertion notify(3) string
* Processes creating assertions listen on this string to enable/disable
* backtrace collection. When backtrace collected, processes send backtrace
* to powerd along with create request.
*/
#define kIOPMAssertionsCollectBTString "com.apple.powermanagement.collectbt"
/*!
* @constant kIOPMAssertionsLogBufferHighWM
* @discussion Assertion notify(3) string
* Fires when assertion activity log buffer reaches high water mark.
*/
#define kIOPMAssertionsLogBufferHighWM "com.apple.powermanagement.assertions.logHighWM"
/*!
* @constant kIOPMDisableAppSleepPrefix
* @discussion Assertion notify(3) string
* Fires when a process raises an assertion of a type that can prevent app sleep.
* This notification is posted only if power assertions are not currently preventing that app's sleep.
*
* Note: This is a prefix only. Actual notification will be appended with PID of the process
* creating the power assertion. eg. com.apple.system.powermanagement.disableappsleep.1234
*
*/
#define kIOPMDisableAppSleepPrefix "com.apple.system.powermanagement.disableappsleep"
/*!
* @constant kIOPMEnableAppSleepPrefix
* @discussion Assertion notify(3) string
* Fires when there are no more active assertions that can prevent app sleep from a process.
* This notification is posted only if app sleep is currently prevented due to power assertions.
*
* Note: This is a prefix only. Actual notification will be appended with PID of the process
* creating the power assertion. eg. com.apple.system.powermanagement.enableappsleep.1234
*
*/
#define kIOPMEnableAppSleepPrefix "com.apple.system.powermanagement.enableappsleep"
/*!
* @constant kIOPMLastWakeTimeString
* @discussion Assertion notify(3) string
* Last wake time is posted on this string after powerd calculates the value on wake.
*
*/
#define kIOPMLastWakeTimeString "com.apple.powermanagement.lastwaketime"
/*!
* @constant kIOPMLastWakeTimeSMCDataString
* @discussion Assertion notify(3) string
* Last wake time obtained from SMC is posted on this string after powerd calculates the value on wake.
*
*/
#define kIOPMLastWakeTimeSMCDataString "com.apple.powermanagement.lastwaketimesmcdata"
/*!
* @define kIOPMAssertionTimeoutActionKillProcess
*
* @discussion When a timeout expires with this action, Power Management will log the timeout event,
* and will kill the process that created the assertion. Signal SIGTERM is issued to
* that process.
*/
#define kIOPMAssertionTimeoutActionKillProcess CFSTR("TimeoutActionKillProcess")
/*! @function IOPMPerformBlockWithAssertion
*
* @abstract Runs a caller-specified block while holding a power assertion.
*
* @discussion This is a convenience API, it can simplify some power assertion uses.
*
* @param assertion_properties is a CFDictionary describing the assertion to hold while
* executing <code>the_block</code>. See headerdoc comments for
* <comment>IOPMAssertionCreateWithProperties</code> describing dictionary format.
*
* @param the_block is a block that doesn't take any arguments. IOPMPerformBlockWithAssertion
* will invoke the_block synchronously on the calling thread, and run until it completes.
*
* @result Returns kIOReturnSuccess when the block is executed.
* Otherwise, appropriate error code is returned.
*/
IOReturn IOPMPerformBlockWithAssertion(CFDictionaryRef assertion_properties, dispatch_block_t the_block);
/*! @function IOPMAssertionSetTimeout
* @abstract Set a timeout for the given assertion.
* @discussion When the timeout fires, the assertion will be logged and a general notification
* will be delivered to all interested processes. The notification will not identify the
* timed-out assertion. The assertion will remain valid & in effect until it's released (if ever).
* Timeouts are bad! Timeouts are a hardcore last chance for debugging hard to find assertion
* leaks. They are not meant to fire under any normal circumstances.
*/
IOReturn IOPMAssertionSetTimeout(IOPMAssertionID whichAssertion, CFTimeInterval timeoutInterval);
/*! @function IOPMAssertionCreateWithAutoTimeout
*
* @abstract A variant of IOPMAssertionCreateWithProperties to create assertion with property
* kIOPMAssertionAutoTimesout set to true.
*
* @description Creates an IOPMAssertion with property kIOPMAssertionAutoTimesout set to true.
* It allows the caller to specify the Name, Details, and HumanReadableReason at creation time.
* There are other keys that can further describe an assertion, but most developers don't need
* to use them. Use <code>@link IOPMAssertionSetProperty @/link</code> or
* <code>@link IOPMAssertionCreateWithProperties @/link</code> if you need to specify properties
* that aren't available here.
*
* @param AssertionType An assertion type constant.
* Caller must specify this argument.
*
* @param Name A CFString value to correspond to key <code>@link kIOPMAssertionNameKey@/link</code>.
* Caller must specify this argument.
*
* @param Details A CFString value to correspond to key <code>@link kIOPMAssertionDetailsKey@/link</code>.
* Caller my pass NULL, but it helps power users and administrators identify the
* reasons for this assertion.
*
* @param HumanReadableReason
* A CFString value to correspond to key <code>@link kIOPMAssertionHumanReadableReasonKey@/link</code>.
* Caller may pass NULL, but if it's specified OS X may display it to users
* to describe the active assertions on their system.
*
* @param LocalizationBundlePath
* A CFString value to correspond to key <code>@link kIOPMAssertionLocalizationBundlePathKey@/link</code>.
* This bundle path should include a localization for the string <code>HumanReadableReason</code>
* Caller may pass NULL, but this argument is required if caller specifies <code>HumanReadableReason</code>
*
* @param Timeout Specifies a timeout for this assertion. Pass 0 for no timeout.
* If the timeout value is larger than the auto-timeout value, it may get reduced to auto-timeout value.
*
* @param TimeoutAction Specifies a timeout action. Caller my pass NULL. If a timeout is specified but a TimeoutAction is not,
* the default timeout action is <code>kIOPMAssertionTimeoutActionTurnOff</code>
*
* @param AssertionID (Output) On successful return, contains a unique reference to a PM assertion.
*
* @result kIOReturnSuccess, or another IOKit return code on error.
*/
IOReturn IOPMAssertionCreateWithAutoTimeout(
CFStringRef AssertionType,
CFStringRef Name,
CFStringRef Details,
CFStringRef HumanReadableReason,
CFStringRef LocalizationBundlePath,
CFTimeInterval Timeout,
CFStringRef TimeoutAction,
IOPMAssertionID *AssertionID)
__OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_10_0);
/*! @function IOPMAssertionCreateWithResourceList
*
* @abstract A variant of IOPMAssertionCreateWithProperties to create assertion with property
* kIOPMAssertionResourcesUsed set to specified resources.
*
* @description Creates an IOPMAssertion with property kIOPMAssertionResourcesUsed set to specified resources.
* It allows the caller to specify the Name, Details, and HumanReadableReason at creation time.
* There are other keys that can further describe an assertion, but most developers don't need
* to use them. Use <code>@link IOPMAssertionSetProperty @/link</code> or
* <code>@link IOPMAssertionCreateWithProperties @/link</code> if you need to specify properties
* that aren't available here.
*
* @param AssertionType An assertion type constant.
* Caller must specify this argument.
*
* @param Name A CFString value to correspond to key <code>@link kIOPMAssertionNameKey@/link</code>.
* Caller must specify this argument.
*
* @param Details A CFString value to correspond to key <code>@link kIOPMAssertionDetailsKey@/link</code>.
* Caller my pass NULL, but it helps power users and administrators identify the
* reasons for this assertion.
*
* @param HumanReadableReason
* A CFString value to correspond to key <code>@link kIOPMAssertionHumanReadableReasonKey@/link</code>.
* Caller may pass NULL, but if it's specified OS X may display it to users
* to describe the active assertions on their system.
*
* @param LocalizationBundlePath
* A CFString value to correspond to key <code>@link kIOPMAssertionLocalizationBundlePathKey@/link</code>.
* This bundle path should include a localization for the string <code>HumanReadableReason</code>
* Caller may pass NULL, but this argument is required if caller specifies <code>HumanReadableReason</code>
*
* @param Timeout Specifies a timeout for this assertion. Pass 0 for no timeout.
*
* @param TimeoutAction Specifies a timeout action. Caller my pass NULL. If a timeout is specified but a TimeoutAction is not,
* the default timeout action is <code>kIOPMAssertionTimeoutActionTurnOff</code>
*
* @param Resources A CFArray with the list of resources used by the process while holding this assertion. Possible values
* are listed with the documentation of <code>kIOPMAssertionResourcesUsed</code>
*
* @param AssertionID (Output) On successful return, contains a unique reference to a PM assertion.
*
* @result kIOReturnSuccess, or another IOKit return code on error.
*/
IOReturn IOPMAssertionCreateWithResourceList(