libkern/libkern/c++/OSString.h

   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
  37 class OSData;
  38 class OSString;
  39
  40 typedef OSPtr<OSString> OSStringPtr;
  41 typedef OSPtr<const OSString> OSStringConstPtr;
  42
  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         * string;
 121
 122 #else /* APPLE_KEXT_ALIGN_CONTAINERS */
 123
 124 protected:
 125         char         * 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 OSStringPtr 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 OSStringPtr 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 OSStringPtr withCStringNoCopy(const char * cString);
 200
 201 #if XNU_KERNEL_PRIVATE
 202         static OSStringPtr withStringOfLength(const char *cString, size_t length);
 203 #endif  /* XNU_KERNEL_PRIVATE */
 204
 205 /*!
 206  * @function initWithString
 207  *
 208  * @abstract
 209  * Initializes an OSString from another OSString.
 210  *
 211  * @param aString   The OSString object whose contents to copy.
 212  *
 213  * @result
 214  * <code>true</code> on success, <code>false</code> on failure.
 215  *
 216  * @discussion
 217  * Not for general use. Use the static instance creation method
 218  * <code>@link withString withString@/link</code> instead.
 219  */
 220         virtual bool initWithString(const OSString * aString);
 221
 222
 223 /*!
 224  * @function initWithCString
 225  *
 226  * @abstract
 227  * Initializes an OSString from a C string.
 228  *
 229  * @param cString   The C string to copy into the new OSString.
 230  *
 231  * @result
 232  * <code>true</code> on success, <code>false</code> on failure.
 233  *
 234  * @discussion
 235  * Not for general use. Use the static instance creation method
 236  * <code>@link withCString withCString@/link</code> instead.
 237  */
 238         virtual bool initWithCString(const char * cString);
 239
 240
 241 /*!
 242  * @function initWithCStringNoCopy
 243  *
 244  * @abstract
 245  * Initializes an immutable OSString
 246  * to share the provided C string buffer.
 247  *
 248  * @param cString   The C string to reference.
 249  *
 250  * @result
 251  * <code>true</code> on success, <code>false</code> on failure.
 252  *
 253  * @discussion
 254  * Not for general use. Use the static instance creation method
 255  * <code>@link withCStringNoCopy withCStringNoCopy@/link</code> instead.
 256  *
 257  * An OSString object initialized with this function
 258  * does not claim ownership of the C string,
 259  * but shares it with the caller.
 260  * When the caller determines that the OSString object has actually been freed,
 261  * it can safely dispose of the data buffer.
 262  * Conversely, if it frees the shared data buffer,
 263  * it must not attempt to use the OSString object and should release it.
 264  *
 265  * An OSString object created with this function does not
 266  * allow changing the string via <code>@link setChar setChar@/link</code>.
 267  */
 268         virtual bool initWithCStringNoCopy(const char * cString);
 269
 270 #if XNU_KERNEL_PRIVATE
 271         bool initWithStringOfLength(const char *cString, size_t inlength);
 272 #endif  /* XNU_KERNEL_PRIVATE */
 273
 274 /*!
 275  * @function free
 276  *
 277  * @abstract
 278  * Deallocates or releases any resources
 279  * used by the OSString instance.
 280  *
 281  * @discussion
 282  * This function should not be called directly;
 283  * use
 284  * <code>@link
 285  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 286  * release@/link</code>
 287  * instead.
 288  */
 289         virtual void free() APPLE_KEXT_OVERRIDE;
 290
 291
 292 /*!
 293  * @function getLength
 294  *
 295  * @abstract
 296  * Returns the number of characters in the OSString object.
 297  *
 298  * @result
 299  * The number of characters in the OSString object.
 300  */
 301         virtual unsigned int getLength() const;
 302
 303
 304 /*!
 305  * @function getChar
 306  *
 307  * @abstract
 308  * Returns the character at a given index in the string object.
 309  *
 310  * @param index The index into the string.
 311  *
 312  * @result
 313  * The character at <code>index</code> within the string,
 314  * or <code>'\0'</code> if index is past the end of the string.
 315  */
 316         virtual char getChar(unsigned int index) const;
 317
 318
 319 /*!
 320  * @function setChar
 321  *
 322  * @abstract
 323  * Replaces a character at a given index in the string object.
 324  *
 325  * @param aChar The character value to set.
 326  * @param index The index into the string.
 327  *
 328  * @result
 329  * <code>true</code> if the character was replaced,
 330  * <code>false</code> if the was created "NoCopy"
 331  * or <code>index</code> is past the end of the string.
 332  */
 333         virtual bool setChar(char aChar, unsigned int index);
 334
 335
 336 /*!
 337  * @function getCStringNoCopy
 338  *
 339  * @abstract
 340  * Returns a pointer to the internal C string buffer.
 341  *
 342  * @result
 343  * A pointer to the internal C string buffer.
 344  */
 345         virtual const char * getCStringNoCopy() const;
 346
 347
 348 /*!
 349  * @function isEqualTo
 350  *
 351  * @abstract
 352  * Tests the equality of two OSString objects.
 353  *
 354  * @param aString  The OSString object being compared against the receiver.
 355  *
 356  * @result
 357  * <code>true</code> if the two OSString objects are equivalent,
 358  * <code>false</code> otherwise.
 359  *
 360  * @discussion
 361  * Two OSString objects are considered equal if they have same length
 362  * and if their byte buffers hold the same contents.
 363  */
 364         virtual bool isEqualTo(const OSString * aString) const;
 365
 366
 367 /*!
 368  * @function isEqualTo
 369  *
 370  * @abstract
 371  * Tests the equality of an OSString object with a C string.
 372  *
 373  * @param cString  The C string to compare against the receiver.
 374  *
 375  * @result
 376  * <code>true</code> if the OSString's characters
 377  * are equivalent to the C string's,
 378  * <code>false</code> otherwise.
 379  */
 380         virtual bool isEqualTo(const char * cString) const;
 381
 382
 383 /*!
 384  * @function isEqualTo
 385  *
 386  * @abstract
 387  * Tests the equality of an OSString object to an arbitrary object.
 388  *
 389  * @param anObject The object to be compared against the receiver.
 390  *
 391  * @result
 392  * Returns <code>true</code> if the two objects are equivalent,
 393  * <code>false</code> otherwise.
 394  *
 395  * @discussion
 396  * An OSString is considered equal to another object
 397  * if that object is derived from OSString
 398  * and contains the equivalent bytes of the same length.
 399  */
 400         virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;
 401
 402
 403 /*!
 404  * @function isEqualTo
 405  *
 406  * @abstract
 407  * Tests the equality of an OSData object and the OSString instance.
 408  *
 409  * @param aDataObject An OSData object.
 410  *
 411  * @result
 412  * <code>true</code> if the two objects are equivalent, <code>false</code> otherwise.
 413  *
 414  * @discussion
 415  * This function compares the bytes of the OSData object
 416  * against those of the OSString,
 417  * accounting for the possibility that an OSData
 418  * might explicitly include a nul
 419  * character as part of its total length.
 420  * Thus, for example, an OSData object containing
 421  * either the bytes <'u', 's', 'b', '\0'>
 422  * or  <'u', 's', 'b'>
 423  * will compare as equal to the OSString containing "usb".
 424  */
 425         virtual bool isEqualTo(const OSData * aDataObject) const;
 426
 427
 428 /*!
 429  * @function serialize
 430  *
 431  * @abstract
 432  * Archives the receiver into the provided
 433  * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 434  *
 435  * @param serializer The OSSerialize object.
 436  *
 437  * @result
 438  * <code>true</code> if serialization succeeds, <code>false</code> if not.
 439  */
 440         virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
 441
 442         OSMetaClassDeclareReservedUnused(OSString, 0);
 443         OSMetaClassDeclareReservedUnused(OSString, 1);
 444         OSMetaClassDeclareReservedUnused(OSString, 2);
 445         OSMetaClassDeclareReservedUnused(OSString, 3);
 446         OSMetaClassDeclareReservedUnused(OSString, 4);
 447         OSMetaClassDeclareReservedUnused(OSString, 5);
 448         OSMetaClassDeclareReservedUnused(OSString, 6);
 449         OSMetaClassDeclareReservedUnused(OSString, 7);
 450         OSMetaClassDeclareReservedUnused(OSString, 8);
 451         OSMetaClassDeclareReservedUnused(OSString, 9);
 452         OSMetaClassDeclareReservedUnused(OSString, 10);
 453         OSMetaClassDeclareReservedUnused(OSString, 11);
 454         OSMetaClassDeclareReservedUnused(OSString, 12);
 455         OSMetaClassDeclareReservedUnused(OSString, 13);
 456         OSMetaClassDeclareReservedUnused(OSString, 14);
 457         OSMetaClassDeclareReservedUnused(OSString, 15);
 458 };
 459
 460 #endif /* !_OS_OSSTRING_H */