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