1/*
2 * Copyright (c) 1998-2019 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29#ifndef _IOKIT_IOSERVICESTATENOTIFICATIONEVENTSOURCE_H
30#define _IOKIT_IOSERVICESTATENOTIFICATIONEVENTSOURCE_H
31
32#include <libkern/c++/OSPtr.h>
33#include <IOKit/IOEventSource.h>
34
35class IOService;
36
37
38/*! @class IOServiceStateNotificationEventSource : public IOEventSource
39 * @abstract Event source for IOService state notification delivery to work-loop based drivers.
40 * @discussion For use with the IOService.iig IOService::StateNotification* APIs.
41 */
42
43class IOServiceStateNotificationEventSource : public IOEventSource
44{
45 OSDeclareDefaultStructors(IOServiceStateNotificationEventSource);
46
47public:
48 typedef void (^ActionBlock)();
49
50protected:
51 IOService * fStateNotification;
52 IOStateNotificationListenerRef fListener;
53 bool fEnable;
54 bool fArmed;
55
56/*! @struct ExpansionData
57 * @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
58 */
59
60/*! @var reserved
61 * Reserved for future use. (Internal use only) */
62 APPLE_KEXT_WSHADOW_PUSH;
63 ExpansionData *reserved;
64 APPLE_KEXT_WSHADOW_POP;
65
66/*! @function free
67 * @abstract Sub-class implementation of free method, disconnects from the interrupt source. */
68 virtual void free() APPLE_KEXT_OVERRIDE;
69
70/*! @function checkForWork
71 * @abstract Pure Virtual member function used by IOWorkLoop for issueing a client calls.
72 * @discussion This function called when the work-loop is ready to check for any work to do and then to call out the owner/action.
73 * @result Return true if this function needs to be called again before all its outstanding events have been processed. */
74 virtual bool checkForWork() APPLE_KEXT_OVERRIDE;
75
76/*! @function setWorkLoop
77 * @abstract Sub-class implementation of setWorkLoop method. */
78 virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE;
79
80public:
81
82 /*!
83 * @brief Create an IOServiceStateNotificationEventSource for notification of IOService state events sent by the StateNotificationSet() api.
84 * @param service The object hosting state, typically returned by IOService::CopySystemStateNotificationService().
85 * @param items Array of state item names to be notified about.
86 * @param action Handler block to be invoked on the event source workloop when the notification fires.
87 * @return IOServiceStateNotificationEventSource with +1 retain, or NULL on failure.
88 */
89 static OSPtr<IOServiceStateNotificationEventSource>
90 serviceStateNotificationEventSource(IOService *service,
91 OSArray * items,
92 ActionBlock action);
93
94/*! @function enable
95 * @abstract Enable event source.
96 * @discussion A subclass implementation is expected to respect the enabled
97 * state when checkForWork is called. Calling this function will cause the
98 * work-loop to be signalled so that a checkForWork is performed. */
99 virtual void enable() APPLE_KEXT_OVERRIDE;
100
101/*! @function disable
102 * @abstract Disable event source.
103 * @discussion A subclass implementation is expected to respect the enabled
104 * state when checkForWork is called. */
105 virtual void disable() APPLE_KEXT_OVERRIDE;
106
107private:
108 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 0);
109 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 1);
110 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 2);
111 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 3);
112 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 4);
113 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 5);
114 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 6);
115 OSMetaClassDeclareReservedUnused(IOServiceStateNotificationEventSource, 7);
116};
117
118#endif /* !_IOKIT_IOSERVICESTATENOTIFICATIONEVENTSOURCE_H */
119