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 /* IOString.h created by rsulack on Wed 17-Sep-1997 */ 29 /* IOString.h converted to C++ by gvdl on Fri 1998-10-30 */ 30 31 #ifndef _OS_OSSTRING_H 32 #define _OS_OSSTRING_H 33 34 #include <libkern/c++/OSObject.h> 35 #include <libkern/c++/OSPtr.h> 36 #include <os/base.h> 37 38 class OSData; 39 class OSString; 40 41 typedef OSString* OSStringPtr; 42 typedef OSString const* OSStringConstPtr; 43 44 /*! 45 * @header 46 * 47 * @abstract 48 * This header declares the OSString container class. 49 */ 50 51 52 /* Not to be included in headerdoc. 53 * 54 * For internal use. 55 */ 56 enum { 57 kOSStringNoCopy = 0x001, 58 #if XNU_KERNEL_PRIVATE 59 kOSSSymbolHashed = 0x002, 60 kOSSSymbolPermanent = 0x004, 61 #endif /* XNU_KERNEL_PRIVATE */ 62 }; 63 64 65 /*! 66 * @class OSString 67 * 68 * @abstract 69 * OSString wraps a C string in a C++ object for use in Libkern collections. 70 * 71 * @discussion 72 * OSString is a container class for managing arrays of characters. 73 * An OSString normally maintains its own character buffer and allows changes, 74 * but you can create an "immutable" OSString 75 * that references an external C string 76 * buffer using the "NoCopy" creator functions. 77 * Functions called to change the contents of an immutable OSString will fail. 78 * 79 * <b>Encodings</b> 80 * 81 * OSString makes no provisions for different character encodings and 82 * assumes that a string is a nul-terminated sequence of single-byte characters. 83 * User-space code must either assume an encoding (typically ASCII or UTF-8) 84 * or determine it in some other way (such as an IORegistryEntry property). 85 * 86 * <b>Altering Strings</b> 87 * 88 * OSString's indended use is as a reference-counted object container 89 * for a C string and little more. 90 * While OSString provides full access to the underlying C string, 91 * it provides little in the way of string object manipulation; 92 * there are no append or insert functions, 93 * only a set-character function. 94 * If you need to manipulate OSStrings, 95 * it's generally best to get the C strings, 96 * alter them as necessary, and create a new OSString object 97 * from the resulting C string. 98 * 99 * <b>Use Restrictions</b> 100 * 101 * With very few exceptions in the I/O Kit, all Libkern-based C++ 102 * classes, functions, and macros are <b>unsafe</b> 103 * to use in a primary interrupt context. 104 * Consult the I/O Kit documentation related to primary interrupts 105 * for more information. 106 * 107 * OSString provides no concurrency protection; 108 * it's up to the usage context to provide any protection necessary. 109 * Some portions of the I/O Kit, such as 110 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, 111 * handle synchronization via defined member functions for setting 112 * properties. 113 */ 114 class OSString : public OSObject 115 { 116 OSDeclareDefaultStructors(OSString); 117 118 enum { kMaxStringLength = 262142 }; 119 120 #if APPLE_KEXT_ALIGN_CONTAINERS 121 122 protected: 123 124 unsigned int flags:14, 125 length:18; 126 char * OS_PTRAUTH_SIGNED_PTR("OSString.string") string; 127 128 #else /* APPLE_KEXT_ALIGN_CONTAINERS */ 129 130 protected: 131 char * OS_PTRAUTH_SIGNED_PTR("OSString.string") string; 132 unsigned int flags; 133 unsigned int length; 134 135 #endif /* APPLE_KEXT_ALIGN_CONTAINERS */ 136 137 public: 138 139 /*! 140 * @function withString 141 * 142 * @abstract 143 * Creates and initializes an OSString from another OSString. 144 * 145 * @param aString The OSString object whose contents to copy. 146 * 147 * @result 148 * An instance of OSString representing 149 * the same characters as <code>aString</code>, 150 * and with a reference count of 1; 151 * <code>NULL</code> on failure. 152 * 153 * @discussion 154 * The new OSString is a distinct instance from <code>aString</code>, 155 * and is not merely the original object 156 * with the reference count incremented. 157 * Changes to one will not be reflected in the other. 158 */ 159 static OSPtr<OSString> withString(const OSString * aString); 160 161 162 /*! 163 * @function withCString 164 * 165 * @abstract 166 * Creates and initializes an OSString from a C string. 167 * 168 * @param cString The C string to copy into the new OSString. 169 * 170 * @result 171 * An instance of OSString representing 172 * the same characters as <code>aString</code>, 173 * and with a reference count of 1; 174 * <code>NULL</code> on failure. 175 */ 176 static OSPtr<OSString> withCString(const char * cString); 177 178 179 /*! 180 * @function withCStringNoCopy 181 * 182 * @abstract 183 * Creates and initializes an immutable OSString 184 * that shares the provided C string buffer. 185 * 186 * @param cString The C string to reference. 187 * 188 * @result 189 * An instance of OSString containing <code>cString</code>, 190 * and with a reference count of 1; 191 * <code>NULL</code> on failure. 192 * 193 * @discussion 194 * An OSString object created with this function 195 * does not claim ownership of the C string, 196 * but shares it with the caller. 197 * When the caller determines that the OSString object has actually been freed, 198 * it can safely dispose of the data buffer. 199 * Conversely, if it frees the shared data buffer, 200 * it must not attempt to use the OSString object and should release it. 201 * 202 * An OSString object created with this function does not 203 * allow changing the string via <code>@link setChar setChar@/link</code>. 204 */ 205 static OSPtr<OSString> withCStringNoCopy(const char * cString); 206 207 /*! 208 * @function withCString 209 * 210 * @abstract 211 * Creates and initializes an OSString from a C string and the given length. 212 * 213 * @param cString The C string to copy into the new OSString. 214 * @param length Number of characters to copy from cString. If the actual length of the 215 * C string is less than this length, then the length of the resulting 216 * OSString will be the same as that of the C cstring. 217 * 218 * @result 219 * An instance of OSString representing 220 * the same characters as <code>cString</code> with the specified length, 221 * and with a reference count of 1; 222 * <code>NULL</code> on failure. 223 */ 224 static OSPtr<OSString> withCString(const char *cString, size_t length); 225 226 /*! 227 * @function initWithString 228 * 229 * @abstract 230 * Initializes an OSString from another OSString. 231 * 232 * @param aString The OSString object whose contents to copy. 233 * 234 * @result 235 * <code>true</code> on success, <code>false</code> on failure. 236 * 237 * @discussion 238 * Not for general use. Use the static instance creation method 239 * <code>@link withString withString@/link</code> instead. 240 */ 241 virtual bool initWithString(const OSString * aString); 242 243 244 /*! 245 * @function initWithCString 246 * 247 * @abstract 248 * Initializes an OSString from a C string. 249 * 250 * @param cString The C string to copy into the new OSString. 251 * 252 * @result 253 * <code>true</code> on success, <code>false</code> on failure. 254 * 255 * @discussion 256 * Not for general use. Use the static instance creation method 257 * <code>@link withCString withCString@/link</code> instead. 258 */ 259 virtual bool initWithCString(const char * cString); 260 261 262 /*! 263 * @function initWithCStringNoCopy 264 * 265 * @abstract 266 * Initializes an immutable OSString 267 * to share the provided C string buffer. 268 * 269 * @param cString The C string to reference. 270 * 271 * @result 272 * <code>true</code> on success, <code>false</code> on failure. 273 * 274 * @discussion 275 * Not for general use. Use the static instance creation method 276 * <code>@link withCStringNoCopy withCStringNoCopy@/link</code> instead. 277 * 278 * An OSString object initialized with this function 279 * does not claim ownership of the C string, 280 * but shares it with the caller. 281 * When the caller determines that the OSString object has actually been freed, 282 * it can safely dispose of the data buffer. 283 * Conversely, if it frees the shared data buffer, 284 * it must not attempt to use the OSString object and should release it. 285 * 286 * An OSString object created with this function does not 287 * allow changing the string via <code>@link setChar setChar@/link</code>. 288 */ 289 virtual bool initWithCStringNoCopy(const char * cString); 290 291 #if XNU_KERNEL_PRIVATE 292 bool initWithStringOfLength(const char *cString, size_t inlength); 293 #endif /* XNU_KERNEL_PRIVATE */ 294 295 /*! 296 * @function free 297 * 298 * @abstract 299 * Deallocates or releases any resources 300 * used by the OSString instance. 301 * 302 * @discussion 303 * This function should not be called directly; 304 * use 305 * <code>@link 306 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() 307 * release@/link</code> 308 * instead. 309 */ 310 virtual void free() APPLE_KEXT_OVERRIDE; 311 312 313 /*! 314 * @function getLength 315 * 316 * @abstract 317 * Returns the number of characters in the OSString object. 318 * 319 * @result 320 * The number of characters in the OSString object. 321 */ 322 virtual unsigned int getLength() const; 323 324 325 /*! 326 * @function getChar 327 * 328 * @abstract 329 * Returns the character at a given index in the string object. 330 * 331 * @param index The index into the string. 332 * 333 * @result 334 * The character at <code>index</code> within the string, 335 * or <code>'\0'</code> if index is past the end of the string. 336 */ 337 virtual char getChar(unsigned int index) const; 338 339 340 /*! 341 * @function setChar 342 * 343 * @abstract 344 * Replaces a character at a given index in the string object. 345 * 346 * @param aChar The character value to set. 347 * @param index The index into the string. 348 * 349 * @result 350 * <code>true</code> if the character was replaced, 351 * <code>false</code> if the was created "NoCopy" 352 * or <code>index</code> is past the end of the string. 353 */ 354 virtual bool setChar(char aChar, unsigned int index); 355 356 357 /*! 358 * @function getCStringNoCopy 359 * 360 * @abstract 361 * Returns a pointer to the internal C string buffer. 362 * 363 * @result 364 * A pointer to the internal C string buffer. 365 */ 366 virtual const char * getCStringNoCopy() const; 367 368 369 /*! 370 * @function isEqualTo 371 * 372 * @abstract 373 * Tests the equality of two OSString objects. 374 * 375 * @param aString The OSString object being compared against the receiver. 376 * 377 * @result 378 * <code>true</code> if the two OSString objects are equivalent, 379 * <code>false</code> otherwise. 380 * 381 * @discussion 382 * Two OSString objects are considered equal if they have same length 383 * and if their byte buffers hold the same contents. 384 */ 385 virtual bool isEqualTo(const OSString * aString) const; 386 387 388 /*! 389 * @function isEqualTo 390 * 391 * @abstract 392 * Tests the equality of an OSString object with a C string. 393 * 394 * @param cString The C string to compare against the receiver. 395 * 396 * @result 397 * <code>true</code> if the OSString's characters 398 * are equivalent to the C string's, 399 * <code>false</code> otherwise. 400 */ 401 virtual bool isEqualTo(const char * cString) const; 402 403 404 /*! 405 * @function isEqualTo 406 * 407 * @abstract 408 * Tests the equality of an OSString object to an arbitrary object. 409 * 410 * @param anObject The object to be compared against the receiver. 411 * 412 * @result 413 * Returns <code>true</code> if the two objects are equivalent, 414 * <code>false</code> otherwise. 415 * 416 * @discussion 417 * An OSString is considered equal to another object 418 * if that object is derived from OSString 419 * and contains the equivalent bytes of the same length. 420 */ 421 virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE; 422 423 424 /*! 425 * @function isEqualTo 426 * 427 * @abstract 428 * Tests the equality of an OSData object and the OSString instance. 429 * 430 * @param aDataObject An OSData object. 431 * 432 * @result 433 * <code>true</code> if the two objects are equivalent, <code>false</code> otherwise. 434 * 435 * @discussion 436 * This function compares the bytes of the OSData object 437 * against those of the OSString, 438 * accounting for the possibility that an OSData 439 * might explicitly include a nul 440 * character as part of its total length. 441 * Thus, for example, an OSData object containing 442 * either the bytes <'u', 's', 'b', '\0'> 443 * or <'u', 's', 'b'> 444 * will compare as equal to the OSString containing "usb". 445 */ 446 virtual bool isEqualTo(const OSData * aDataObject) const; 447 448 449 /*! 450 * @function serialize 451 * 452 * @abstract 453 * Archives the receiver into the provided 454 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object. 455 * 456 * @param serializer The OSSerialize object. 457 * 458 * @result 459 * <code>true</code> if serialization succeeds, <code>false</code> if not. 460 */ 461 virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE; 462 463 OSMetaClassDeclareReservedUnused(OSString, 0); 464 OSMetaClassDeclareReservedUnused(OSString, 1); 465 OSMetaClassDeclareReservedUnused(OSString, 2); 466 OSMetaClassDeclareReservedUnused(OSString, 3); 467 OSMetaClassDeclareReservedUnused(OSString, 4); 468 OSMetaClassDeclareReservedUnused(OSString, 5); 469 OSMetaClassDeclareReservedUnused(OSString, 6); 470 OSMetaClassDeclareReservedUnused(OSString, 7); 471 OSMetaClassDeclareReservedUnused(OSString, 8); 472 OSMetaClassDeclareReservedUnused(OSString, 9); 473 OSMetaClassDeclareReservedUnused(OSString, 10); 474 OSMetaClassDeclareReservedUnused(OSString, 11); 475 OSMetaClassDeclareReservedUnused(OSString, 12); 476 OSMetaClassDeclareReservedUnused(OSString, 13); 477 OSMetaClassDeclareReservedUnused(OSString, 14); 478 OSMetaClassDeclareReservedUnused(OSString, 15); 479 }; 480 481 #endif /* !_OS_OSSTRING_H */ 482