libkern/libkern/c++/OSData.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 /* IOData.h created by rsulack on Wed 17-Sep-1997 */
  31 /* IOData.h converted to C++ by gvdl on Fri 1998-10-30 */
  32
  33 #ifndef _OS_OSDATA_H
  34 #define _OS_OSDATA_H
  35
  36 #include <libkern/c++/OSObject.h>
  37
  38 class OSString;
  39
  40 /*!
  41     @class OSData
  42     @abstract A container class to manage an array of bytes.
  43 */
  44 class OSData : public OSObject
  45 {
  46     OSDeclareDefaultStructors(OSData)
  47
  48 protected:
  49     void        *data;
  50     unsigned int length;
  51     unsigned int capacity;
  52     unsigned int capacityIncrement;
  53
  54     struct ExpansionData { };
  55
  56     /*! @var reserved
  57         Reserved for future use.  (Internal use only)  */
  58     ExpansionData *reserved;
  59
  60 public:
  61     /*!
  62         @function withCapacity
  63         @abstract A static constructor function to create and initialize an empty instance of OSData with a given capacity.
  64         @param inCapacity The initial capacity of the OSData object in bytes.
  65         @result Returns an instance of OSData or 0 if a failure occurs.
  66     */
  67     static OSData *withCapacity(unsigned int inCapacity);
  68     /*!
  69         @function withBytes
  70         @abstract A static constructor function to create and initialize an instance of OSData and copies in the provided data.
  71         @param bytes A buffer of data.
  72         @param inLength The size of the given buffer.
  73         @result Returns an instance of OSData or 0 if a failure occurs.
  74     */
  75     static OSData *withBytes(const void *bytes, unsigned int inLength);
  76     /*!
  77         @function withBytesNoCopy
  78         @abstract A static constructor function to create and initialize an instance of OSData which references a buffer of data.
  79         @param bytes A reference to a block of data.
  80         @param inLength The size of the data block.
  81         @result Returns an instance of OSData or 0 if a failure occurs.
  82     */
  83     static OSData *withBytesNoCopy(void *bytes, unsigned int inLength);
  84     /*!
  85         @function withData
  86         @abstract A static constructor function to create and initialize an instance of OSData with the data provided.
  87         @param inData An OSData object which provides the initial data.
  88         @result Returns an instance of OSData or 0 if a failure occurs.
  89     */
  90     static OSData *withData(const OSData *inData);
  91     /*!
  92         @function withData
  93         @abstract A static constructor function to create and initialize an instance of OSData with a specific range of the data provided.
  94         @param inData An OSData object which provides the initial data.
  95         @param start The starting index at which the data will be copied.
  96         @param inLength The number of bytes to be copied starting at index 'start'.
  97         @result Returns an instance of OSData or 0 if a failure occurs.
  98     */
  99     static OSData *withData(const OSData *inData,
 100                                 unsigned int start, unsigned int inLength);
 101
 102     /*!
 103         @function initWithCapacity
 104         @abstract A member function to initialize an instance of OSData with a minimum capacity of at least the given size.  If this function is called an an object that has been previously used then the length is set down to 0 and a new block of data is allocated if necessary to ensure the given capacity.
 105         @param capacity The length of the allocated block of data.
 106         @result Returns true if initialization was successful, false otherwise.
 107     */
 108     virtual bool initWithCapacity(unsigned int capacity);
 109     /*!
 110         @function initWithBytes
 111         @abstract A member function to initialize an instance of OSData which references a block of data.
 112         @param bytes A reference to a block of data
 113         @param inLength The length of the block of data.
 114         @result Returns true if initialization was successful, false otherwise.
 115     */
 116     virtual bool initWithBytes(const void *bytes, unsigned int inLength);
 117     /*!
 118         @function initWithBytes
 119         @abstract A member function to initialize an instance of OSData which references a block of data.
 120         @param bytes A reference to a block of data
 121         @param inLength The length of the block of data.
 122         @result Returns true if initialization was successful, false otherwise.
 123     */
 124     virtual bool initWithBytesNoCopy(void *bytes, unsigned int inLength);
 125     /*!
 126         @function initWithData
 127         @abstract A member function to initialize an instance of OSData with the data provided.
 128         @param inData An OSData object which provides the data to be copied.
 129         @result Returns true if initialization was successful, false otherwise.
 130     */
 131     virtual bool initWithData(const OSData *inData);
 132     /*!
 133         @function initWithData
 134         @abstract A member function to initialize an instance of OSData with a specific range of the data provided
 135         @param inData An OSData object.
 136         @param start The starting range of data to be copied.
 137         @param inLength The length in bytes of the data to be copied.
 138         @result Returns true if initialization was successful, false otherwise.
 139     */
 140     virtual bool initWithData(const OSData *inData,
 141                               unsigned int start, unsigned int inLength);
 142     /*!
 143         @function free
 144         @abstract A member function which releases all resources created or used by the OSData object.
 145         @discussion Do not call this function directly, use release() instead.
 146     */
 147     virtual void free();
 148
 149     /*!
 150         @function getLength
 151         @abstract A member function which returns the length of the internal data buffer.
 152         @result Returns an integer value for the length of data in the object's internal data buffer.
 153     */
 154     virtual unsigned int getLength() const;
 155     /*!
 156         @function getCapacity
 157         @abstract A member function which returns the capacity of the internal data buffer.
 158         @result Returns an integer value for the size of the object's internal data buffer.
 159     */
 160     virtual unsigned int getCapacity() const;
 161     /*!
 162         @function getCapacityIncrement
 163         @abstract A member function which returns the size by which the data buffer will grow.
 164         @result Returns the size by which the data buffer will grow.
 165     */
 166     virtual unsigned int getCapacityIncrement() const;
 167     /*!
 168         @function setCapacityIncrement
 169         @abstract A member function which sets the growth size of the data buffer.
 170         @result Returns the new growth size.
 171     */
 172     virtual unsigned int setCapacityIncrement(unsigned increment);
 173     /*!
 174         @function ensureCapacity
 175         @abstract A member function which will expand the size of the collection to a given storage capacity.
 176         @param newCapacity The new capacity for the data buffer.
 177         @result Returns the new capacity of the data buffer or the previous capacity upon error.
 178     */
 179     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 180     /*!
 181         @function appendBytes
 182         @abstract A member function which appends a buffer of data onto the end of the object's internal data buffer.
 183         @param bytes A pointer to the block of data.  If the value is 0 then append zero-ed memory to the data object.
 184         @param inLength The length of the data block.
 185         @result Returns true if the object was able to append the new data, false otherwise.
 186     */
 187     virtual bool appendBytes(const void *bytes, unsigned int inLength);
 188     /*!
 189         @function appendBytes
 190         @abstract A member function which appends the data contained in an OSData object to the receiver.
 191         @param other An OSData object.
 192         @result Returns true if appending the new data was successful, false otherwise.
 193     */
 194     virtual bool appendBytes(const OSData *other);
 195
 196     /*!
 197         @function getBytesNoCopy
 198         @abstract A member function to return a pointer to the OSData object's internal data buffer.
 199         @result Returns a reference to the OSData object's internal data buffer.
 200     */
 201     virtual const void *getBytesNoCopy() const;
 202     /*!
 203         @function getBytesNoCopy
 204         @abstract Returns a reference into the OSData object's internal data buffer at particular offset and with a particular length.
 205         @param start The offset from the base of the internal data buffer.
 206         @param inLength The length of window.
 207         @result Returns a pointer at a particular offset into the data buffer, or 0 if the starting offset or length are not valid.
 208     */
 209     virtual const void *getBytesNoCopy(unsigned int start,
 210                                        unsigned int inLength) const;
 211
 212     /*!
 213         @function isEqualTo
 214         @abstract A member function to test the equality of two OSData objects.
 215         @param aData The OSData object to be compared to the receiver.
 216         @result Returns true if the two objects are equivalent, false otherwise.
 217     */
 218     virtual bool isEqualTo(const OSData *aData) const;
 219     /*!
 220         @function isEqualTo
 221         @abstract A member function to test the equality of an arbitrary block of data with the OSData object's internal data buffer.
 222         @param someData A pointer to a block of data.
 223         @param inLength The length of the block of data.
 224         @result Returns true if the two blocks of data are equivalent, false otherwise.
 225     */
 226     virtual bool isEqualTo(const void *someData, unsigned int inLength) const;
 227     /*!
 228         @function isEqualTo
 229         @abstract A member function to test the equality between an OSData object and an arbitrary OSObject derived object.
 230         @param obj An OSObject derived object.
 231         @result Returns true if the two objects are equivalent.
 232     */
 233     virtual bool isEqualTo(const OSMetaClassBase *obj) const;
 234     /*!
 235         @function isEqualTo
 236         @abstract A member function to test the equality between an OSData object and an OSString object.
 237         @param obj An OSString object
 238         @result Returns true if the two objects are equivalent.
 239     */
 240     virtual bool isEqualTo(const OSString *obj) const;
 241     /*!
 242         @function serialize
 243         @abstract A member function which archives the receiver.
 244         @param s The OSSerialize object.
 245         @result Returns true if serialization was successful, false if not.
 246     */
 247     virtual bool serialize(OSSerialize *s) const;
 248
 249     /*!
 250         @function appendByte
 251         @abstract A member function which appends a buffer of constant data onto the end of the object's internal data buffer.
 252         @param byte A byte value to replicate as the added data.
 253         @param inCount The length of the data to add.
 254         @result Returns true if the object was able to append the new data, false otherwise.
 255     */
 256     virtual bool appendByte(unsigned char byte, unsigned int inCount);
 257
 258
 259
 260 private:
 261     OSMetaClassDeclareReservedUnused(OSData, 0);
 262     OSMetaClassDeclareReservedUnused(OSData, 1);
 263     OSMetaClassDeclareReservedUnused(OSData, 2);
 264     OSMetaClassDeclareReservedUnused(OSData, 3);
 265     OSMetaClassDeclareReservedUnused(OSData, 4);
 266     OSMetaClassDeclareReservedUnused(OSData, 5);
 267     OSMetaClassDeclareReservedUnused(OSData, 6);
 268     OSMetaClassDeclareReservedUnused(OSData, 7);
 269 };
 270
 271 #endif /* !_OS_OSDATA_H */