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