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 */
71class OSNumber : public OSObject
72{
73 friend class OSSerialize;
74
75 OSDeclareDefaultStructors(OSNumber)
76
77#if APPLE_KEXT_ALIGN_CONTAINERS
78
79protected:
80 unsigned int size;
81 unsigned long long value;
82
83#else /* APPLE_KEXT_ALIGN_CONTAINERS */
84
85protected:
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
96public:
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