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 | |
35 | class 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 | */ |
63 | class OSBoolean : public OSObject |
64 | { |
65 | OSDeclareDefaultStructors(OSBoolean) |
66 | friend class OSSerialize; |
67 | |
68 | protected: |
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 | |
85 | public: |
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 | */ |
254 | extern 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 | */ |
270 | extern OSBoolean * const & kOSBooleanFalse; |
271 | |
272 | #endif /* !_OS_OSBOOLEAN_H */ |
273 | |