libkern/libkern/c++/OSNumber.h

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