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 35 class 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 43 class IOServiceStateNotificationEventSource : public IOEventSource 44 { 45 OSDeclareDefaultStructors(IOServiceStateNotificationEventSource); 46 47 public: 48 typedef void (^ActionBlock)(); 49 50 protected: 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 80 public: 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 107 private: 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