1/*
2 * Copyright (c) 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/* OSBoolean.cpp created by rsulack on Tue Oct 12 1999 */
29
30#ifndef _OS_OSBOOLEAN_H
31#define _OS_OSBOOLEAN_H
32
33#include <libkern/c++/OSObject.h>
34#include <libkern/c++/OSPtr.h>
35
36class OSString;
37class OSBoolean;
38
39typedef OSBoolean* OSBooleanPtr;
40
41/*!
42 * @header
43 *
44 * @abstract
45 * This header declares the OSBoolean container class.
46 */
47
48
49/*!
50 * @class OSBoolean
51 *
52 * @abstract
53 * OSBoolean wraps a boolean value in a C++ object
54 * for use in Libkern collections.
55 *
56 * @discussion
57 * OSBoolean represents a boolean <code>true</code>/<code>false</code> value
58 * as a Libkern C++ object.
59 * There are only two instances of OSBoolean,
60 * <code>@link kOSBooleanTrue kOSBooleanTrue@/link</code>
61 * and <code>@link kOSBooleanFalse kOSBooleanFalse@/link</code>.
62 * These are shared globally and returned by the instance-creation function
63 * <code>@link withBoolean withBoolean@/link</code>.
64 * Thus, you can use pointer comparison
65 * to test whether two OSBoolean objects are equal.
66 */
67class OSBoolean : public OSObject
68{
69 OSDeclareDefaultStructors(OSBoolean);
70 friend class OSSerialize;
71
72protected:
73 bool value;
74
75/*!
76 * @function taggedRelease
77 *
78 * @abstract
79 * Overrides the reference counting mechanism
80 * for the shared global instances.
81 *
82 * @param tag Unused.
83 * @param when Unused.
84 */
85 virtual void taggedRelease(
86 const void * tag,
87 const int when) const APPLE_KEXT_OVERRIDE;
88
89public:
90 static void initialize();
91
92/*!
93 * @function withBoolean
94 *
95 * @abstract
96 * Returns one of the global instances of OSBoolean.
97 *
98 * @param value A boolean value.
99 *
100 * @result
101 * The global instance of OSBoolean with the boolean <code>value</code>.
102 *
103 * @discussion
104 * This function actually returns either
105 * <code>@link kOSBooleanTrue kOSBooleanTrue@/link</code> or
106 * <code>@link kOSBooleanFalse kOSBooleanFalse@/link</code>,
107 * so that you can always use pointer comparison with OSBoolean objects.
108 */
109 static OSPtr<OSBoolean> withBoolean(bool value) __returns_nonnull_osptr;
110
111/*!
112 * @function free
113 *
114 * @abstract
115 * Overridden to prevent deallocation of the shared global instances.
116 *
117 * @discussion
118 * This function should never be called.
119 */
120 virtual void free() APPLE_KEXT_OVERRIDE;
121
122
123/*!
124 * @function taggedRetain
125 *
126 * @abstract
127 * Overrides the reference counting mechanism for the shared global instances.
128 *
129 * @param tag Unused.
130 */
131 virtual void taggedRetain(const void * tag) const APPLE_KEXT_OVERRIDE;
132
133
134/*!
135 * @function isTrue
136 *
137 * @abstract
138 * Checks whether the OSBoolean object
139 * represents a <code>true</code> <code>bool</code> value.
140 *
141 * @result
142 * <code>true</code> if the OSBoolean object is <code>true</code>,
143 * <code>false</code> otherwise.
144 *
145 * @discussion
146 * You can also use <code>==</code> against
147 * <code>@link kOSBooleanTrue kOSBooleanTrue@/link</code>.
148 */
149 virtual bool isTrue() const;
150
151
152/*!
153 * @function isFalse
154 *
155 * @abstract
156 * Checks whether the OSBoolean object
157 * represents a <code>false</code> <code>bool</code> value.
158 *
159 * @result
160 * <code>true</code> if the OSBoolean object is <code>false</code>,
161 * <code>true</code> otherwise.
162 *
163 * @discussion
164 * You can also use <code>==</code> against
165 * <code>@link kOSBooleanFalse kOSBooleanFalse@/link</code>.
166 */
167 virtual bool isFalse() const;
168
169
170/*!
171 * @function getValue
172 *
173 * @abstract
174 * Returns the C++ <code>bool</code> value for the OSBoolean object.
175 *
176 * @result
177 * Returns the C++ <code>bool</code> value of the OSBoolean object.
178 */
179 virtual bool getValue() const;
180
181
182/*!
183 * @function isEqualTo
184 *
185 * @abstract
186 * Tests the equality of two OSBoolean objects.
187 *
188 * @param aBoolean The OSBoolean to be compared against the receiver.
189 *
190 * @result
191 * <code>true</code> if the OSBoolean objects are equal,
192 * <code>false</code> if not.
193 *
194 * @discussion
195 * Two OSBoolean objects are considered equal
196 * if they are the same exact object (pointer equality).
197 */
198 virtual bool isEqualTo(const OSBoolean * aBoolean) const;
199
200
201/*!
202 * @function isEqualTo
203 *
204 * @abstract
205 * Tests the equality an OSBoolean to an arbitrary object.
206 *
207 * @param anObject An object to be compared against the receiver.
208 *
209 * @result
210 * <code>true</code> if the objects are equal, <code>false</code> if not.
211 *
212 * @discussion
213 * An OSBoolean is considered equal to another object
214 * if that object is derived from OSBoolean
215 * and represents the same C++ <code>bool</code> value.
216 */
217 virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;
218
219
220/*!
221 * @function serialize
222 *
223 * @abstract
224 * Archives the receiver into the provided
225 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
226 *
227 * @param serializer The OSSerialize object.
228 *
229 * @result
230 * <code>true</code> if serialization succeeds, <code>false</code> if not.
231 */
232 virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
233
234 OSMetaClassDeclareReservedUnused(OSBoolean, 0);
235 OSMetaClassDeclareReservedUnused(OSBoolean, 1);
236 OSMetaClassDeclareReservedUnused(OSBoolean, 2);
237 OSMetaClassDeclareReservedUnused(OSBoolean, 3);
238 OSMetaClassDeclareReservedUnused(OSBoolean, 4);
239 OSMetaClassDeclareReservedUnused(OSBoolean, 5);
240 OSMetaClassDeclareReservedUnused(OSBoolean, 6);
241 OSMetaClassDeclareReservedUnused(OSBoolean, 7);
242};
243
244/*!
245 * @const kOSBooleanTrue
246 *
247 * @abstract
248 * The OSBoolean constant for <code>true</code>.
249 *
250 * @discussion
251 * kOSBooleanTrue is the OSBoolean constant for <code>true</code>.
252 * This object does not need to be retained or released (but it can be).
253 * Comparisons of the form
254 * <code>booleanObject == kOSBooleanTrue</code>
255 * are acceptable and are equivalent to
256 * <code>booleanObject->getValue() == true</code>.
257 */
258extern OSBoolean * const & kOSBooleanTrue;
259
260/*!
261 * @const kOSBooleanFalse
262 *
263 * @abstract
264 * The OSBoolean constant for <code>false</code>.
265 *
266 * @discussion
267 * kOSBooleanFalse is the OSBoolean constant for <code>false</code>.
268 * This object does not need to be retained or released (but it can be).
269 * Comparisons of the form
270 * <code>booleanObject == kOSBooleanFalse</code>
271 * are acceptable and are equivalent to
272 * <code>booleanObject->getValue() == false</code>.
273 */
274extern OSBoolean * const & kOSBooleanFalse;
275
276#endif /* !_OS_OSBOOLEAN_H */
277