iokit/DriverKit/OSAction.iig

   1 /*
   2  * Copyright (c) 2019-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_OSACTION_H
  30 #define _IOKIT_OSACTION_H
  31
  32 #include <DriverKit/OSObject.iig>
  33
  34 typedef void (^OSActionCancelHandler)(void);
  35 typedef void (^OSActionAbortedHandler)(void);
  36
  37 /*!
  38  * @class OSAction
  39  *
  40  * @abstract
  41  * OSAction is an object that represents a callback to be be invoked.
  42  *
  43  * @discussion
  44  * The callback is specified as a method and object pair.
  45  * State associated with the callback may be allocated and stored for the creator of the object.
  46  * Methods to allocate an OSAction instance are generated for each method defined in a class with
  47  * a TYPE attribute, so there should not be any need to directly call OSAction::Create().
  48  */
  49
  50 class NATIVE KERNEL OSAction : public OSObject
  51 {
  52 public:
  53
  54     /*!
  55      * @brief       Create an instance of OSAction.
  56          * @discussion  Methods to allocate an OSAction instance are generated for each method defined in a class with
  57      *              a TYPE attribute, so there should not be any need to directly call OSAction::Create().
  58      * @param       target OSObject to receive the callback. This object will be retained until the OSAction is
  59      *              canceled or freed.
  60      * @param       targetmsgid Generated message ID for the target method.
  61      * @param       msgid Generated message ID for the method invoked by the receiver of the OSAction
  62      *              to generate the callback.
  63      * @param       referenceSize Size of additional state structure available to the creator of the OSAction
  64      *              with GetReference.
  65      * @param       action Created OSAction with +1 retain count to be released by the caller.
  66      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  67      */
  68         static kern_return_t
  69         Create(
  70                 OSObject      * target,
  71                 uint64_t        targetmsgid,
  72                 uint64_t        msgid,
  73                 size_t          referenceSize,
  74                 OSAction     ** action) LOCAL;
  75
  76         virtual void
  77         free() override;
  78
  79     /*!
  80      * @brief       Return a pointer to any state allocated by the OSAction creator.
  81      * @discussion  Reference data is allocated with zero initialized content. It may be set and retrieved later
  82      *              with this method.
  83      * @return      A pointer to storage for the owner. It will be NULL if referenceSize was zero, and NULL
  84      *              when called in a process other than the owner that is receiving the OSAction as a parameter.
  85      */
  86         void *
  87         GetReference() LOCALONLY;
  88
  89     /*!
  90      * @brief       Cancel all callbacks from the action.
  91      * @discussion  After cancellation, the action can only be freed. It cannot be reactivated.
  92      * @param       handler Handler block to be invoked after any callbacks have completed.
  93      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  94      */
  95         kern_return_t
  96         Cancel(OSActionCancelHandler handler) LOCALONLY;
  97
  98     /*!
  99      * @brief       Install a handler to be invoked when no other processes reference the action.
 100      * @discussion  When all tasks other than the creator release their references to the action,
 101      *              invoke the handler in the owner. A task exiting will always remove its references.
 102      * @param       handler Handler block to be invoked on no more references.
 103      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 104      */
 105         kern_return_t
 106         SetAbortedHandler(OSActionAbortedHandler handler) LOCALONLY;
 107
 108         virtual void
 109         Aborted(void) LOCAL;
 110 };
 111
 112 #endif /* ! _IOKIT_OSACTION_H */