/*
* Copyright (c) 2019-2019 Apple Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_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. The rights granted to you under the License
* may not be used to create, or enable the creation or redistribution of,
* unlawful or unlicensed copies of an Apple operating system, or to
* circumvent, violate, or enable the circumvention or violation of, any
* terms of an Apple operating system software license agreement.
*
* 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_OSREFERENCE_LICENSE_HEADER_END@
*/
#ifndef _IOKIT_UIOSERVICESTATEDISPATCHSOURCE_H
#define _IOKIT_UIOSERVICESTATEDISPATCHSOURCE_H
#include <DriverKit/IODispatchQueue.iig>
#include <DriverKit/OSAction.iig>
#include <DriverKit/IOService.iig>
class NATIVE KERNEL IOServiceStateNotificationDispatchSource : public IODispatchSource
{
public:
virtual bool
init() override;
virtual void
free() override;
/*!
* @brief Create an IOServiceStateNotificationDispatchSource for notification of IOService state events sent by the StateNotificationSet() api.
* @param service The object hosting state, typically returned by IOService::CopySystemStateNotificationService().
* @param items Array of state item names to be notified about.
* @param queue IODispatchQueue the source is attached to. Note that the StateNotificationReady
* handler is invoked on the queue set for the target method
* of the OSAction, not this queue.
* @param source Created source with +1 retain count to be released by the caller.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
static kern_return_t
Create(IOService * service, OSArray * items, IODispatchQueue * queue, IOServiceStateNotificationDispatchSource ** source) LOCAL;
/*!
* @brief Control the enable state of the notification.
* @param enable Pass true to enable the source or false to disable.
* @param handler Optional block to be executed after the interrupt has been disabled and any pending
* interrupt handlers completed.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
SetEnableWithCompletion(
bool enable,
IODispatchSourceCancelHandler handler) override LOCAL;
/*!
* @brief Cancel all callbacks from the event source.
* @discussion After cancellation, the source can only be freed. It cannot be reactivated.
* @param handler Handler block to be invoked after any callbacks have completed.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
Cancel(IODispatchSourceCancelHandler handler) override LOCAL;
/*!
* @brief Set the handler block to run when the notification has become ready.
* @param action OSAction instance specifying the callback method. The OSAction object will be retained
* until SetHandler is called again or the event source is cancelled.
* The StateNotificationReady handler is invoked on the queue set for the target method of the
* OSAction.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
SetHandler(
OSAction * action TYPE(StateNotificationReady));
/*!
* @brief Rearm the notification.
* @discussion Call this method in the implementation of your StateNotificationReady action
* before reading any item values.
* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
*/
virtual kern_return_t
StateNotificationBegin(void);
private:
virtual void
StateNotificationReady(
OSAction * action TARGET) LOCAL = 0;
};
#endif /* ! _IOKIT_UIOSERVICESTATEDISPATCHSOURCE_H */