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 | |
36 | class 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 | */ |
103 | class OSString : public OSObject |
104 | { |
105 | |
106 | OSDeclareDefaultStructors(OSString) |
107 | |
108 | enum { kMaxStringLength = 262142 }; |
109 | |
110 | #if APPLE_KEXT_ALIGN_CONTAINERS |
111 | |
112 | protected: |
113 | |
114 | unsigned int flags:14, |
115 | length:18; |
116 | char * string; |
117 | |
118 | #else /* APPLE_KEXT_ALIGN_CONTAINERS */ |
119 | |
120 | protected: |
121 | char * string; |
122 | unsigned int flags; |
123 | unsigned int length; |
124 | |
125 | #endif /* APPLE_KEXT_ALIGN_CONTAINERS */ |
126 | |
127 | public: |
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 | |