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
38class OSData;
39class OSString;
40
41typedef OSString* OSStringPtr;
42typedef 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 */
56enum {
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 */
114class OSString : public OSObject
115{
116 OSDeclareDefaultStructors(OSString);
117
118 enum { kMaxStringLength = 262142 };
119
120#if APPLE_KEXT_ALIGN_CONTAINERS
121
122protected:
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
130protected:
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
137public:
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