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