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