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 | /* IOOffset.h created by rsulack on Wed 17-Sep-1997 */ |
29 | /* IOOffset.h converted to C++ by gvdl on Fri 1998-10-30 */ |
30 | |
31 | #ifndef _OS_OSNUMBER_H |
32 | #define _OS_OSNUMBER_H |
33 | |
34 | #include <libkern/c++/OSObject.h> |
35 | |
36 | /*! |
37 | * @header |
38 | * |
39 | * @abstract |
40 | * This header declares the OSNumber container class. |
41 | */ |
42 | |
43 | |
44 | /*! |
45 | * @class OSNumber |
46 | * |
47 | * @abstract |
48 | * OSNumber wraps an integer value in a C++ object |
49 | * for use in Libkern collections. |
50 | * |
51 | * @discussion |
52 | * OSNumber represents an integer of 8, 16, 32, or 64 bits |
53 | * as a Libkern C++ object. |
54 | * OSNumber objects are mutable: you can add to or set their values. |
55 | * |
56 | * <b>Use Restrictions</b> |
57 | * |
58 | * With very few exceptions in the I/O Kit, all Libkern-based C++ |
59 | * classes, functions, and macros are <b>unsafe</b> |
60 | * to use in a primary interrupt context. |
61 | * Consult the I/O Kit documentation related to primary interrupts |
62 | * for more information. |
63 | * |
64 | * OSNumber provides no concurrency protection; |
65 | * it's up to the usage context to provide any protection necessary. |
66 | * Some portions of the I/O Kit, such as |
67 | * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, |
68 | * handle synchronization via defined member functions for setting |
69 | * properties. |
70 | */ |
71 | class OSNumber : public OSObject |
72 | { |
73 | friend class OSSerialize; |
74 | |
75 | OSDeclareDefaultStructors(OSNumber) |
76 | |
77 | #if APPLE_KEXT_ALIGN_CONTAINERS |
78 | |
79 | protected: |
80 | unsigned int size; |
81 | unsigned long long value; |
82 | |
83 | #else /* APPLE_KEXT_ALIGN_CONTAINERS */ |
84 | |
85 | protected: |
86 | unsigned long long value; |
87 | unsigned int size; |
88 | |
89 | struct ExpansionData { }; |
90 | |
91 | /* Reserved for future use. (Internal use only) */ |
92 | ExpansionData * reserved; |
93 | |
94 | #endif /* APPLE_KEXT_ALIGN_CONTAINERS */ |
95 | |
96 | public: |
97 | |
98 | /*! |
99 | * @function withNumber |
100 | * |
101 | * @abstract |
102 | * Creates and initializes an instance of OSNumber |
103 | * with an integer value. |
104 | * |
105 | * @param value The numeric integer value for the OSNumber to store. |
106 | * @param numberOfBits The number of bits to limit storage to. |
107 | * |
108 | * @result |
109 | * An instance of OSNumber with a reference count of 1; |
110 | * <code>NULL</code> on failure. |
111 | * |
112 | * @discussion |
113 | * <code>value</code> is masked to the provided <code>numberOfBits</code> |
114 | * when the OSNumber object is initialized. |
115 | * |
116 | * You can change the value of an OSNumber later |
117 | * using <code>@link setValue setValue@/link</code> |
118 | * and <code>@link addValue addValue@/link</code>, |
119 | * but you can't change the bit size. |
120 | */ |
121 | static OSNumber * withNumber( |
122 | unsigned long long value, |
123 | unsigned int numberOfBits); |
124 | |
125 | |
126 | /*! |
127 | * @function withNumber |
128 | * |
129 | * @abstract |
130 | * Creates and initializes an instance of OSNumber |
131 | * with an unsigned integer value represented as a C string. |
132 | * |
133 | * @param valueString A C string representing a numeric value |
134 | * for the OSNumber to store. |
135 | * @param numberOfBits The number of bits to limit storage to. |
136 | * |
137 | * @result |
138 | * An instance of OSNumber with a reference count of 1; |
139 | * <code>NULL</code> on failure. |
140 | * |
141 | * @discussion |
142 | * This function does not work in I/O Kit versions prior to 8.0 (Mac OS X 10.4). |
143 | * In I/O Kit version 8.0 and later, it works |
144 | * but is limited to parsing unsigned 32 bit quantities. |
145 | * The format of the C string may be decimal, hexadecimal ("0x" prefix), |
146 | * binary ("0b" prefix), or octal ("0" prefix). |
147 | * |
148 | * The parsed value is masked to the provided <code>numberOfBits</code> |
149 | * when the OSNumber object is initialized. |
150 | * |
151 | * You can change the value of an OSNumber later |
152 | * using <code>@link setValue setValue@/link</code> |
153 | * and <code>@link addValue addValue@/link</code>, |
154 | * but you can't change the bit size. |
155 | */ |
156 | static OSNumber * withNumber( |
157 | const char * valueString, |
158 | unsigned int numberOfBits); |
159 | |
160 | |
161 | /*! |
162 | * @function init |
163 | * |
164 | * @abstract |
165 | * Initializes an instance of OSNumber with an integer value. |
166 | * |
167 | * @param value The numeric integer value for the OSNumber to store. |
168 | * @param numberOfBits The number of bits to limit storage to. |
169 | * |
170 | * @result |
171 | * <code>true</code> if initialization succeeds, |
172 | * <code>false</code> on failure. |
173 | * |
174 | * @discussion |
175 | * Not for general use. Use the static instance creation method |
176 | * <code>@link |
177 | * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint) |
178 | * withNumber(unsigned long long, unsigned int)@/link</code> |
179 | * instead. |
180 | */ |
181 | virtual bool init( |
182 | unsigned long long value, |
183 | unsigned int numberOfBits); |
184 | |
185 | |
186 | /*! |
187 | * @function init |
188 | * |
189 | * @abstract |
190 | * Initializes an instance of OSNumber |
191 | * with an unsigned integer value represented as a C string. |
192 | * |
193 | * @param valueString A C string representing a numeric value |
194 | * for the OSNumber to store. |
195 | * @param numberOfBits The number of bits to limit storage to. |
196 | * |
197 | * @result |
198 | * <code>true</code> if initialization succeeds, |
199 | * <code>false</code> on failure. |
200 | * |
201 | * @discussion |
202 | * Not for general use. Use the static instance creation method |
203 | * <code>@link |
204 | * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint) |
205 | * withNumber(const char *, unsigned int)@/link</code> |
206 | * instead. |
207 | */ |
208 | virtual bool init( |
209 | const char * valueString, |
210 | unsigned int numberOfBits); |
211 | |
212 | |
213 | /*! |
214 | * @function free |
215 | * |
216 | * @abstract |
217 | * Deallocates or releases any resources |
218 | * used by the OSNumber instance. |
219 | * |
220 | * @discussion |
221 | * This function should not be called directly; |
222 | * use |
223 | * <code>@link |
224 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
225 | * release@/link</code> |
226 | * instead. |
227 | */ |
228 | virtual void free() APPLE_KEXT_OVERRIDE; |
229 | |
230 | |
231 | /*! |
232 | * @function numberOfBits |
233 | * |
234 | * @abstract |
235 | * Returns the number of bits used to represent |
236 | * the OSNumber object's integer value. |
237 | * |
238 | * @result |
239 | * The number of bits used to represent |
240 | * the OSNumber object's integer value. |
241 | * |
242 | * @discussion |
243 | * The number of bits is used to limit the stored value of the OSNumber. |
244 | * Any change to its value is performed as an <code>unsigned long long</code> |
245 | * and then truncated to the number of bits. |
246 | */ |
247 | virtual unsigned int numberOfBits() const; |
248 | |
249 | |
250 | /*! |
251 | * @function numberOfBytes |
252 | * |
253 | * @abstract |
254 | * Returns the number of bytes used to represent |
255 | * the OSNumber object's integer value. |
256 | * |
257 | * @result |
258 | * The number of bytes used to represent |
259 | * the OSNumber object's integer value. |
260 | * See <code>@link numberOfBits numberOfBits@/link</code>. |
261 | */ |
262 | virtual unsigned int numberOfBytes() const; |
263 | |
264 | |
265 | // xx-review: should switch to explicitly-sized int types |
266 | // xx-review: but that messes up C++ mangled symbols :-( |
267 | |
268 | |
269 | /*! |
270 | * @function unsigned8BitValue |
271 | * |
272 | * @abstract |
273 | * Returns the OSNumber object's integer value |
274 | * cast as an unsigned 8-bit integer. |
275 | * |
276 | * @result |
277 | * The OSNumber object's integer value |
278 | * cast as an unsigned 8-bit integer. |
279 | * |
280 | * @discussion |
281 | * This function merely casts the internal integer value, |
282 | * giving no indication of truncation or other potential conversion problems. |
283 | */ |
284 | virtual unsigned char unsigned8BitValue() const; |
285 | |
286 | |
287 | /*! |
288 | * @function unsigned16BitValue |
289 | * |
290 | * @abstract |
291 | * Returns the OSNumber object's integer value |
292 | * cast as an unsigned 16-bit integer. |
293 | * |
294 | * @result |
295 | * Returns the OSNumber object's integer value |
296 | * cast as an unsigned 16-bit integer. |
297 | * |
298 | * @discussion |
299 | * This function merely casts the internal integer value, |
300 | * giving no indication of truncation or other potential conversion problems. |
301 | */ |
302 | virtual unsigned short unsigned16BitValue() const; |
303 | |
304 | |
305 | /*! |
306 | * @function unsigned32BitValue |
307 | * |
308 | * @abstract |
309 | * Returns the OSNumber object's integer value |
310 | * cast as an unsigned 32-bit integer. |
311 | * |
312 | * @result |
313 | * Returns the OSNumber object's integer value |
314 | * cast as an unsigned 32-bit integer. |
315 | * |
316 | * @discussion |
317 | * This function merely casts the internal integer value, |
318 | * giving no indication of truncation or other potential conversion problems. |
319 | */ |
320 | virtual unsigned int unsigned32BitValue() const; |
321 | |
322 | |
323 | /*! |
324 | * @function unsigned64BitValue |
325 | * |
326 | * @abstract |
327 | * Returns the OSNumber object's integer value |
328 | * cast as an unsigned 64-bit integer. |
329 | * |
330 | * @result |
331 | * Returns the OSNumber object's integer value |
332 | * cast as an unsigned 64-bit integer. |
333 | * |
334 | * @discussion |
335 | * This function merely casts the internal integer value, |
336 | * giving no indication of truncation or other potential conversion problems. |
337 | */ |
338 | virtual unsigned long long unsigned64BitValue() const; |
339 | |
340 | // xx-review: wow, there's no addNumber(OSNumber *)! |
341 | |
342 | /*! |
343 | * @function addValue |
344 | * |
345 | * @abstract |
346 | * Adds a signed integer value to the internal integer value |
347 | * of the OSNumber object. |
348 | * |
349 | * @param value The value to be added. |
350 | * |
351 | * @discussion |
352 | * This function adds values as 64-bit integers, |
353 | * but masks the result by the bit size |
354 | * (see <code>@link numberOfBits numberOfBits@/link</code>), |
355 | * so addition overflows will not necessarily |
356 | * be the same as for plain C integers. |
357 | */ |
358 | virtual void addValue(signed long long value); |
359 | |
360 | |
361 | /*! |
362 | * @function setValue |
363 | * |
364 | * @abstract |
365 | * Replaces the current internal integer value |
366 | * of the OSNumber object by the value given. |
367 | * |
368 | * @param value The new value for the OSNumber object, |
369 | * which is truncated by the bit size of the OSNumber object |
370 | * (see <code>@link numberOfBits numberOfBits@/link</code>). |
371 | */ |
372 | virtual void setValue(unsigned long long value); |
373 | |
374 | |
375 | /*! |
376 | * @function isEqualTo |
377 | * |
378 | * @abstract |
379 | * Tests the equality of two OSNumber objects. |
380 | * |
381 | * @param aNumber The OSNumber to be compared against the receiver. |
382 | * |
383 | * @result |
384 | * <code>true</code> if the OSNumber objects are equal, |
385 | * <code>false</code> if not. |
386 | * |
387 | * @discussion |
388 | * Two OSNumber objects are considered equal |
389 | * if they represent the same C integer value. |
390 | */ |
391 | virtual bool isEqualTo(const OSNumber * aNumber) const; |
392 | |
393 | |
394 | /*! |
395 | * @function isEqualTo |
396 | * |
397 | * @abstract |
398 | * Tests the equality an OSNumber to an arbitrary object. |
399 | * |
400 | * @param anObject An object to be compared against the receiver. |
401 | * |
402 | * @result |
403 | * <code>true</code> if the objects are equal, |
404 | * <code>false</code> if not. |
405 | * |
406 | * @discussion |
407 | * An OSNumber is considered equal to another object if that object is |
408 | * derived from OSNumber and represents the same C integer value. |
409 | */ |
410 | virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE; |
411 | |
412 | |
413 | /*! |
414 | * @function serialize |
415 | * |
416 | * @abstract |
417 | * Archives the receiver into the provided |
418 | * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object. |
419 | * |
420 | * @param serializer The OSSerialize object. |
421 | * |
422 | * @result |
423 | * <code>true</code> if serialization succeeds, <code>false</code> if not. |
424 | */ |
425 | virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE; |
426 | |
427 | |
428 | OSMetaClassDeclareReservedUnused(OSNumber, 0); |
429 | OSMetaClassDeclareReservedUnused(OSNumber, 1); |
430 | OSMetaClassDeclareReservedUnused(OSNumber, 2); |
431 | OSMetaClassDeclareReservedUnused(OSNumber, 3); |
432 | OSMetaClassDeclareReservedUnused(OSNumber, 4); |
433 | OSMetaClassDeclareReservedUnused(OSNumber, 5); |
434 | OSMetaClassDeclareReservedUnused(OSNumber, 6); |
435 | OSMetaClassDeclareReservedUnused(OSNumber, 7); |
436 | }; |
437 | |
438 | #endif /* !_OS_OSNUMBER_H */ |
439 | |