1/* iig(DriverKit-286) generated from OSAction.iig */
2
3/* OSAction.iig:1-38 */
4/*
5 * Copyright (c) 2019-2019 Apple Inc. All rights reserved.
6 *
7 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
8 *
9 * This file contains Original Code and/or Modifications of Original Code
10 * as defined in and that are subject to the Apple Public Source License
11 * Version 2.0 (the 'License'). You may not use this file except in
12 * compliance with the License. The rights granted to you under the License
13 * may not be used to create, or enable the creation or redistribution of,
14 * unlawful or unlicensed copies of an Apple operating system, or to
15 * circumvent, violate, or enable the circumvention or violation of, any
16 * terms of an Apple operating system software license agreement.
17 *
18 * Please obtain a copy of the License at
19 * http://www.opensource.apple.com/apsl/ and read it before using this file.
20 *
21 * The Original Code and all software distributed under the License are
22 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
23 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
24 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
26 * Please see the License for the specific language governing rights and
27 * limitations under the License.
28 *
29 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
30 */
31
32#ifndef _IOKIT_OSACTION_H
33#define _IOKIT_OSACTION_H
34
35#include <DriverKit/OSObject.h> /* .iig include */
36
37typedef void (^OSActionCancelHandler)(void);
38typedef void (^OSActionAbortedHandler)(void);
39struct OSActionWaitToken;
40class OSString;
41
42/* source class OSAction OSAction.iig:39-170 */
43
44#if __DOCUMENTATION__
45#define KERNEL IIG_KERNEL
46
47/*!
48 * @class OSAction
49 *
50 * @abstract
51 * OSAction is an object that represents a callback to be be invoked.
52 *
53 * @discussion
54 * The callback is specified as a method and object pair.
55 * State associated with the callback may be allocated and stored for the creator of the object.
56 * Methods to allocate an OSAction instance are generated for each method defined in a class with
57 * a TYPE attribute. The generated methods are named CreateAction{name of method with type attribute}
58 * and have the following declaration:
59 *
60 * kern_return_t CreateActionNameOfMethod(size_t referenceSize, OSAction **action);
61 *
62 * referenceSize refers to the size of additional state structure available to the creator of the OSAction
63 * with GetReference. If successful, the generated method returns kIOReturnSuccess and a created OSAction
64 * through the 'action' parameter with a +1 retain count to be released by the caller. See IOReturn.h for
65 * error codes.
66 */
67
68class NATIVE KERNEL OSAction : public OSObject
69{
70public:
71
72#if DRIVERKIT_PRIVATE
73 /*!
74 * @brief Create an instance of OSAction.
75 * @discussion Methods to allocate an OSAction instance are generated for each method defined in a class with
76 * a TYPE attribute, so there should not be any need to directly call OSAction::Create().
77 * @param target OSObject to receive the callback. This object will be retained until the OSAction is
78 * canceled or freed.
79 * @param targetmsgid Generated message ID for the target method.
80 * @param msgid Generated message ID for the method invoked by the receiver of the OSAction
81 * to generate the callback.
82 * @param referenceSize Size of additional state structure available to the creator of the OSAction
83 * with GetReference.
84 * @param action Created OSAction with +1 retain count to be released by the caller.
85 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
86 */
87 static kern_return_t
88 Create(
89 OSObject * target,
90 uint64_t targetmsgid,
91 uint64_t msgid,
92 size_t referenceSize,
93 OSAction ** action) LOCAL;
94
95 static kern_return_t
96 CreateWithTypeName(
97 OSObject * target,
98 uint64_t targetmsgid,
99 uint64_t msgid,
100 size_t referenceSize,
101 OSString * typeName,
102 OSAction ** action) LOCAL;
103#endif
104
105 virtual void
106 free() override;
107
108 /*!
109 * @brief Return a pointer to any state allocated by the OSAction creator.
110 * @discussion Reference data is allocated with zero initialized content. It may be set and retrieved later
111 * with this method.
112 * @return A pointer to storage for the owner. It will be NULL if referenceSize was zero, and NULL
113 * when called in a process other than the owner that is receiving the OSAction as a parameter.
114 */
115 void *
116 GetReference() LOCALONLY;
117
118 /*!
119 * @brief Cancel all callbacks from the action.
120 * @discussion After cancellation, the action can only be freed. It cannot be reactivated.
121 * @param handler Handler block to be invoked after any callbacks have completed.
122 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
123 */
124 kern_return_t
125 Cancel(OSActionCancelHandler handler) LOCALONLY;
126
127 /*!
128 * @brief Install a handler to be invoked when no other processes reference the action.
129 * @discussion When all tasks other than the creator release their references to the action,
130 * invoke the handler in the owner. A task exiting will always remove its references.
131 * @param handler Handler block to be invoked on no more references.
132 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
133 */
134 kern_return_t
135 SetAbortedHandler(OSActionAbortedHandler handler) LOCALONLY;
136
137 /*!
138 * @brief Mark this OSAction to be waited for later with Wait().
139 * @discussion This call should be made before any possible invocation of the action.
140 * An OSAction instance only supports one waiter and WillWait() will return an error if already called.
141 * @param token Opaque value to be passed to a later call to Wait() and EndWait().
142 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
143 */
144 kern_return_t
145 WillWait(OSActionWaitToken ** token) LOCALONLY;
146
147 /*!
148 * @brief Discard the OSActionWaitToken for the action.
149 * @discussion Free any resources needed to wait for the action allocated by WillWait().
150 * There should be no outstanding invocations of the action when EndWait is called,
151 * if necessary the action should be canceled before calling EndWait().
152 * @param token Opaque value to be passed from an earlier call to WillWait().
153 * @return kIOReturnSuccess on success. kIOReturnAborted if aborted or canceled.
154 kIOReturnTimeout if the deadline was passed. See IOReturn.h for error codes.
155 */
156 kern_return_t
157 EndWait(
158 OSActionWaitToken * token) LOCALONLY;
159
160 /*!
161 * @brief Wait for the action to be invoked.
162 * @discussion The current thread is blocked until the action invocation has completed, the action canceled
163 or aborted, or the deadline passed.
164 * @param token Opaque value to be passed from an earlier call to WillWait().
165 * @param options Pass one of the kIOTimerClock* options to specify the timebase for the
166 * deadline, or zero for no timeout.
167 * @param deadline Pass the time the wait should timeout, or zero for no timeout.
168 * @return kIOReturnSuccess on success. kIOReturnAborted if aborted or canceled.
169 kIOReturnTimeout if the deadline was passed. See IOReturn.h for error codes.
170 */
171 kern_return_t
172 Wait(
173 OSActionWaitToken * token,
174 uint64_t options,
175 uint64_t deadline) LOCALONLY;
176
177 virtual void
178 Aborted(void) LOCALHOST;
179};
180
181#undef KERNEL
182#else /* __DOCUMENTATION__ */
183
184/* generated class OSAction OSAction.iig:39-170 */
185
186#define OSAction_Create_ID 0xaa1fc3ce85ce5497ULL
187#define OSAction_CreateWithTypeName_ID 0xa0c5b3ed5a8ea283ULL
188#define OSAction_Aborted_ID 0xbfb95094c657d68fULL
189
190#define OSAction_Create_Args \
191 OSObject * target, \
192 uint64_t targetmsgid, \
193 uint64_t msgid, \
194 size_t referenceSize, \
195 OSAction ** action
196
197#define OSAction_CreateWithTypeName_Args \
198 OSObject * target, \
199 uint64_t targetmsgid, \
200 uint64_t msgid, \
201 size_t referenceSize, \
202 OSString * typeName, \
203 OSAction ** action
204
205#define OSAction_Aborted_Args \
206
207
208#define OSAction_Methods \
209\
210public:\
211\
212 virtual kern_return_t\
213 Dispatch(const IORPC rpc) APPLE_KEXT_OVERRIDE;\
214\
215 static kern_return_t\
216 _Dispatch(OSAction * self, const IORPC rpc);\
217\
218 static kern_return_t\
219 Create(\
220 OSObject * target,\
221 uint64_t targetmsgid,\
222 uint64_t msgid,\
223 size_t referenceSize,\
224 OSAction ** action);\
225\
226 static kern_return_t\
227 CreateWithTypeName(\
228 OSObject * target,\
229 uint64_t targetmsgid,\
230 uint64_t msgid,\
231 size_t referenceSize,\
232 OSString * typeName,\
233 OSAction ** action);\
234\
235 void *\
236 GetReference(\
237);\
238\
239 kern_return_t\
240 Cancel(\
241 OSActionCancelHandler handler);\
242\
243 kern_return_t\
244 SetAbortedHandler(\
245 OSActionAbortedHandler handler);\
246\
247 kern_return_t\
248 WillWait(\
249 OSActionWaitToken ** token);\
250\
251 kern_return_t\
252 EndWait(\
253 OSActionWaitToken * token);\
254\
255 kern_return_t\
256 Wait(\
257 OSActionWaitToken * token,\
258 uint64_t options,\
259 uint64_t deadline);\
260\
261 void\
262 Aborted(\
263 OSDispatchMethod supermethod = NULL);\
264\
265\
266protected:\
267 /* _Impl methods */\
268\
269 static kern_return_t\
270 Create_Call(OSAction_Create_Args);\
271\
272 static kern_return_t\
273 CreateWithTypeName_Call(OSAction_CreateWithTypeName_Args);\
274\
275 void\
276 Aborted_Impl(OSAction_Aborted_Args);\
277\
278\
279public:\
280 /* _Invoke methods */\
281\
282 typedef kern_return_t (*Create_Handler)(OSAction_Create_Args);\
283 static kern_return_t\
284 Create_Invoke(const IORPC rpc,\
285 Create_Handler func);\
286\
287 typedef kern_return_t (*CreateWithTypeName_Handler)(OSAction_CreateWithTypeName_Args);\
288 static kern_return_t\
289 CreateWithTypeName_Invoke(const IORPC rpc,\
290 CreateWithTypeName_Handler func);\
291\
292 typedef void (*Aborted_Handler)(OSMetaClassBase * targetOSAction_Aborted_Args);\
293 static kern_return_t\
294 Aborted_Invoke(const IORPC rpc,\
295 OSMetaClassBase * target,\
296 Aborted_Handler func);\
297\
298
299
300#define OSAction_KernelMethods \
301\
302protected:\
303 /* _Impl methods */\
304\
305 static kern_return_t\
306 Create_Impl(OSAction_Create_Args);\
307\
308 static kern_return_t\
309 CreateWithTypeName_Impl(OSAction_CreateWithTypeName_Args);\
310\
311
312
313#define OSAction_VirtualMethods \
314\
315public:\
316\
317 virtual void\
318 free(\
319) APPLE_KEXT_OVERRIDE;\
320\
321
322
323#if !KERNEL
324
325extern OSMetaClass * gOSActionMetaClass;
326extern const OSClassLoadInformation OSAction_Class;
327
328class OSActionMetaClass : public OSMetaClass
329{
330public:
331 virtual kern_return_t
332 New(OSObject * instance) override;
333 virtual kern_return_t
334 Dispatch(const IORPC rpc) override;
335};
336
337#endif /* !KERNEL */
338
339class OSActionInterface : public OSInterface
340{
341public:
342};
343
344struct OSAction_IVars;
345struct OSAction_LocalIVars;
346
347class OSAction : public OSObject, public OSActionInterface
348{
349#if KERNEL
350 OSDeclareDefaultStructorsWithDispatch(OSAction);
351#endif /* KERNEL */
352
353#if !KERNEL
354 friend class OSActionMetaClass;
355#endif /* !KERNEL */
356
357public:
358#ifdef OSAction_DECLARE_IVARS
359OSAction_DECLARE_IVARS
360#else /* OSAction_DECLARE_IVARS */
361 union
362 {
363 OSAction_IVars * ivars;
364 OSAction_LocalIVars * lvars;
365 };
366#endif /* OSAction_DECLARE_IVARS */
367#if !KERNEL
368 static OSMetaClass *
369 sGetMetaClass() { return gOSActionMetaClass; };
370 virtual const OSMetaClass *
371 getMetaClass() const APPLE_KEXT_OVERRIDE { return gOSActionMetaClass; };
372#endif /* KERNEL */
373
374 using super = OSObject;
375
376#if !KERNEL
377 OSAction_Methods
378#endif /* !KERNEL */
379
380 OSAction_VirtualMethods
381};
382
383#endif /* !__DOCUMENTATION__ */
384
385/* OSAction.iig:172- */
386
387#endif /* ! _IOKIT_OSACTION_H */
388