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 36 class OSString; 37 class OSBoolean; 38 39 typedef 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 */ 67 class OSBoolean : public OSObject 68 { 69 OSDeclareDefaultStructors(OSBoolean); 70 friend class OSSerialize; 71 72 protected: 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 89 public: 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 */ 258 extern 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 */ 274 extern OSBoolean * const & kOSBooleanFalse; 275 276 #endif /* !_OS_OSBOOLEAN_H */ 277