libkern/libkern/c++/OSNumber.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /* IOOffset.h created by rsulack on Wed 17-Sep-1997 */
  31 /* IOOffset.h converted to C++ by gvdl on Fri 1998-10-30 */
  32
  33 #ifndef _OS_OSNUMBER_H
  34 #define _OS_OSNUMBER_H
  35
  36 #include <libkern/c++/OSObject.h>
  37
  38 /*!
  39     @class OSNumber
  40     @abstract A container class for numeric values.
  41 */
  42 class OSNumber : public OSObject
  43 {
  44     OSDeclareDefaultStructors(OSNumber)
  45
  46 protected:
  47     unsigned long long value;
  48     unsigned int size;
  49
  50     struct ExpansionData { };
  51
  52     /*! @var reserved
  53         Reserved for future use.  (Internal use only)  */
  54     ExpansionData *reserved;
  55
  56 public:
  57     /*!
  58         @function withNumber
  59         @abstract A static constructor function to create and initialize an instance of OSNumber with a given value.
  60         @param value The numeric integer value.
  61         @param numberOfBits The number of bit required to represent the value.
  62         @result Returns an instance of OSNumber or 0 if an error occurred.
  63     */
  64     static OSNumber *withNumber(unsigned long long value,
  65                             unsigned int numberOfBits);
  66     /*!
  67         @function withNumber
  68         @abstract A static constructor function to create and initialize an instance of OSNumber with a given value represented as a simple c-string.
  69         @discussion This function does not work on IOKit versions prior to 8.0 (prior to 10.4).  For IOKit version 8.0 and later, it works but is limited to parsing unsigned 32 bit quantities  The format of the c-string may be decimal, hexadecimal ("0x" prefix), binary ("0b" prefix, or octal ("0" prefix).
  70         @param value A c-string representing a numeric value.
  71         @param numberOfBits The number of bit required to represent the value.
  72         @result Returns an instance of OSNumber or 0 if an error occurred.
  73     */
  74     static OSNumber *withNumber(const char *value, unsigned int numberOfBits);
  75
  76     /*!
  77         @function init
  78         @abstract A member function to initialize an instance of OSNumber.
  79         @param value An integer value.
  80         @param numberOfBits The number of bit required to represent the value.
  81         @result Returns true if instance was successfully initialized, false otherwise.
  82     */
  83     virtual bool init(unsigned long long value, unsigned int numberOfBits);
  84     /*!
  85         @function init
  86         @abstract A member function to initialize an instance of OSNumber.
  87         @param value A c-string representation of a numeric value.
  88         @param numberOfBits The number of bit required to represent the value.
  89         @result Returns true if instance was successfully initialized, false otherwise.
  90     */
  91     virtual bool init(const char *value, unsigned int numberOfBits);
  92     /*!
  93         @function free
  94         @abstract Releases and deallocates resources created by the OSNumber instances.
  95         @discussion This function should not be called directly, use release() instead.
  96     */
  97     virtual void free();
  98
  99     /*!
 100         @function numberOfBits
 101         @abstract A member function which returns the number of bits used to represent the value.
 102         @result Returns the number of bits required to represent the value.
 103     */
 104     virtual unsigned int numberOfBits() const;
 105     /*!
 106         @function numberOfBytes
 107         @abstract A member function which returns the number of bytes used to represent the value.
 108         @result Returns the number of bytes required to represent the value.
 109     */
 110     virtual unsigned int numberOfBytes() const;
 111
 112     /*!
 113         @function unsigned8BitValue
 114         @abstract A member function which returns its internal value as an 8-bit value.
 115         @result Returns the internal value as an 8-bit value.
 116     */
 117     virtual unsigned char unsigned8BitValue() const;
 118     /*!
 119         @function unsigned16BitValue
 120         @abstract A member function which returns its internal value as an 16-bit value.
 121         @result Returns the internal value as an 16-bit value.
 122     */
 123     virtual unsigned short unsigned16BitValue() const;
 124     /*!
 125         @function unsigned32BitValue
 126         @abstract A member function which returns its internal value as an 32-bit value.
 127         @result Returns the internal value as an 32-bit value.
 128     */
 129     virtual unsigned int unsigned32BitValue() const;
 130     /*!
 131         @function unsigned64BitValue
 132         @abstract A member function which returns its internal value as an 64-bit value.
 133         @result Returns the internal value as an 64-bit value.
 134     */
 135     virtual unsigned long long unsigned64BitValue() const;
 136
 137     /*!
 138         @function addValue
 139         @abstract A member function which adds an integer value to the internal numeric value of the OSNumber object.
 140         @param value The value to be added.
 141     */
 142     virtual void addValue(signed long long value);
 143     /*!
 144         @function setValue
 145         @abstract Replaces the current internal numeric value of the OSNumber object by the value given.
 146         @param value The new value for the OSNumber object.
 147     */
 148     virtual void setValue(unsigned long long value);
 149
 150     /*!
 151         @function isEqualTo
 152         @abstract A member function to test the equality of two OSNumber objects.
 153         @param integer The OSNumber object to be compared against the receiver.
 154         @result Returns true if the two objects are equivalent, false otherwise.
 155     */
 156     virtual bool isEqualTo(const OSNumber *integer) const;
 157     /*!
 158         @function isEqualTo
 159         @abstract A member function to test the equality of an arbitrary OSObject derived object and an OSNumber object.
 160         @param obj The OSObject derived object to be compared to the receiver.
 161         @result Returns true if the two objects are equivalent, false otherwise.
 162     */
 163     virtual bool isEqualTo(const OSMetaClassBase *obj) const;
 164
 165     /*!
 166         @function serialize
 167         @abstract A member function which archives the receiver.
 168         @param s The OSSerialize object.
 169         @result Returns true if serialization was successful, false if not.
 170     */
 171     virtual bool serialize(OSSerialize *s) const;
 172
 173
 174     OSMetaClassDeclareReservedUnused(OSNumber, 0);
 175     OSMetaClassDeclareReservedUnused(OSNumber, 1);
 176     OSMetaClassDeclareReservedUnused(OSNumber, 2);
 177     OSMetaClassDeclareReservedUnused(OSNumber, 3);
 178     OSMetaClassDeclareReservedUnused(OSNumber, 4);
 179     OSMetaClassDeclareReservedUnused(OSNumber, 5);
 180     OSMetaClassDeclareReservedUnused(OSNumber, 6);
 181     OSMetaClassDeclareReservedUnused(OSNumber, 7);
 182 };
 183
 184 #endif /* !_OS_OSNUMBER_H */