libkern/libkern/c++/OSData.h

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