]>
git.saurik.com Git - apple/xnu.git/blob - libkern/libkern/c++/OSData.h
f35ea6bb25f5c6cd50e511736348d72596c2e69a
2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
4 * @APPLE_LICENSE_HEADER_START@
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. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
21 * @APPLE_LICENSE_HEADER_END@
23 /* IOData.h created by rsulack on Wed 17-Sep-1997 */
24 /* IOData.h converted to C++ by gvdl on Fri 1998-10-30 */
29 #include <libkern/c++/OSObject.h>
35 @abstract A container class to manage an array of bytes.
37 class OSData
: public OSObject
39 OSDeclareDefaultStructors ( OSData
)
44 unsigned int capacity
;
45 unsigned int capacityIncrement
;
47 struct ExpansionData
{ };
50 Reserved for future use. (Internal use only) */
51 ExpansionData
* reserved
;
55 @function withCapacity
56 @abstract A static constructor function to create and initialize an empty instance of OSData with a given capacity.
57 @param inCapacity The initial capacity of the OSData object in bytes.
58 @result Returns an instance of OSData or 0 if a failure occurs.
60 static OSData
* withCapacity ( unsigned int inCapacity
);
63 @abstract A static constructor function to create and initialize an instance of OSData and copies in the provided data.
64 @param bytes A buffer of data.
65 @param inLength The size of the given buffer.
66 @result Returns an instance of OSData or 0 if a failure occurs.
68 static OSData
* withBytes ( const void * bytes
, unsigned int inLength
);
70 @function withBytesNoCopy
71 @abstract A static constructor function to create and initialize an instance of OSData which references a buffer of data.
72 @param bytes A reference to a block of data.
73 @param inLength The size of the data block.
74 @result Returns an instance of OSData or 0 if a failure occurs.
76 static OSData
* withBytesNoCopy ( void * bytes
, unsigned int inLength
);
79 @abstract A static constructor function to create and initialize an instance of OSData with the data provided.
80 @param inData An OSData object which provides the initial data.
81 @result Returns an instance of OSData or 0 if a failure occurs.
83 static OSData
* withData ( const OSData
* inData
);
86 @abstract A static constructor function to create and initialize an instance of OSData with a specific range of the data provided.
87 @param inData An OSData object which provides the initial data.
88 @param start The starting index at which the data will be copied.
89 @param inLength The number of bytes to be copied starting at index 'start'.
90 @result Returns an instance of OSData or 0 if a failure occurs.
92 static OSData
* withData ( const OSData
* inData
,
93 unsigned int start
, unsigned int inLength
);
96 @function initWithCapacity
97 @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.
98 @param capacity The length of the allocated block of data.
99 @result Returns true if initialization was successful, false otherwise.
101 virtual bool initWithCapacity ( unsigned int capacity
);
103 @function initWithBytes
104 @abstract A member function to initialize an instance of OSData which references a block of data.
105 @param bytes A reference to a block of data
106 @param inLength The length of the block of data.
107 @result Returns true if initialization was successful, false otherwise.
109 virtual bool initWithBytes ( const void * bytes
, unsigned int inLength
);
111 @function initWithBytes
112 @abstract A member function to initialize an instance of OSData which references a block of data.
113 @param bytes A reference to a block of data
114 @param inLength The length of the block of data.
115 @result Returns true if initialization was successful, false otherwise.
117 virtual bool initWithBytesNoCopy ( void * bytes
, unsigned int inLength
);
119 @function initWithData
120 @abstract A member function to initialize an instance of OSData with the data provided.
121 @param inData An OSData object which provides the data to be copied.
122 @result Returns true if initialization was successful, false otherwise.
124 virtual bool initWithData ( const OSData
* inData
);
126 @function initWithData
127 @abstract A member function to initialize an instance of OSData with a specific range of the data provided
128 @param inData An OSData object.
129 @param start The starting range of data to be copied.
130 @param inLength The length in bytes of the data to be copied.
131 @result Returns true if initialization was successful, false otherwise.
133 virtual bool initWithData ( const OSData
* inData
,
134 unsigned int start
, unsigned int inLength
);
137 @abstract A member function which releases all resources created or used by the OSData object.
138 @discussion Do not call this function directly, use release() instead.
144 @abstract A member function which returns the length of the internal data buffer.
145 @result Returns an integer value for the length of data in the object's internal data buffer.
147 virtual unsigned int getLength () const ;
149 @function getCapacity
150 @abstract A member function which returns the capacity of the internal data buffer.
151 @result Returns an integer value for the size of the object's internal data buffer.
153 virtual unsigned int getCapacity () const ;
155 @function getCapacityIncrement
156 @abstract A member function which returns the size by which the data buffer will grow.
157 @result Returns the size by which the data buffer will grow.
159 virtual unsigned int getCapacityIncrement () const ;
161 @function setCapacityIncrement
162 @abstract A member function which sets the growth size of the data buffer.
163 @result Returns the new growth size.
165 virtual unsigned int setCapacityIncrement ( unsigned increment
);
167 @function ensureCapacity
168 @abstract A member function which will expand the size of the collection to a given storage capacity.
169 @param newCapacity The new capacity for the data buffer.
170 @result Returns the new capacity of the data buffer or the previous capacity upon error.
172 virtual unsigned int ensureCapacity ( unsigned int newCapacity
);
174 @function appendBytes
175 @abstract A member function which appends a buffer of data onto the end of the object's internal data buffer.
176 @param bytes A pointer to the block of data. If the value is 0 then append zero-ed memory to the data object.
177 @param inLength The length of the data block.
178 @result Returns true if the object was able to append the new data, false otherwise.
180 virtual bool appendBytes ( const void * bytes
, unsigned int inLength
);
182 @function appendBytes
183 @abstract A member function which appends the data contained in an OSData object to the receiver.
184 @param other An OSData object.
185 @result Returns true if appending the new data was successful, false otherwise.
187 virtual bool appendBytes ( const OSData
* other
);
190 @function getBytesNoCopy
191 @abstract A member function to return a pointer to the OSData object's internal data buffer.
192 @result Returns a reference to the OSData object's internal data buffer.
194 virtual const void * getBytesNoCopy () const ;
196 @function getBytesNoCopy
197 @abstract Returns a reference into the OSData object's internal data buffer at particular offset and with a particular length.
198 @param start The offset from the base of the internal data buffer.
199 @param inLength The length of window.
200 @result Returns a pointer at a particular offset into the data buffer, or 0 if the starting offset or length are not valid.
202 virtual const void * getBytesNoCopy ( unsigned int start
,
203 unsigned int inLength
) const ;
207 @abstract A member function to test the equality of two OSData objects.
208 @param aData The OSData object to be compared to the receiver.
209 @result Returns true if the two objects are equivalent, false otherwise.
211 virtual bool isEqualTo ( const OSData
* aData
) const ;
214 @abstract A member function to test the equality of an arbitrary block of data with the OSData object's internal data buffer.
215 @param someData A pointer to a block of data.
216 @param inLength The length of the block of data.
217 @result Returns true if the two blocks of data are equivalent, false otherwise.
219 virtual bool isEqualTo ( const void * someData
, unsigned int inLength
) const ;
222 @abstract A member function to test the equality between an OSData object and an arbitrary OSObject derived object.
223 @param obj An OSObject derived object.
224 @result Returns true if the two objects are equivalent.
226 virtual bool isEqualTo ( const OSMetaClassBase
* obj
) const ;
229 @abstract A member function to test the equality between an OSData object and an OSString object.
230 @param obj An OSString object
231 @result Returns true if the two objects are equivalent.
233 virtual bool isEqualTo ( const OSString
* obj
) const ;
236 @abstract A member function which archives the receiver.
237 @param s The OSSerialize object.
238 @result Returns true if serialization was successful, false if not.
240 virtual bool serialize ( OSSerialize
* s
) const ;
244 @abstract A member function which appends a buffer of constant data onto the end of the object's internal data buffer.
245 @param byte A byte value to replicate as the added data.
246 @param inCount The length of the data to add.
247 @result Returns true if the object was able to append the new data, false otherwise.
249 virtual bool appendByte ( unsigned char byte
, unsigned int inCount
);
254 OSMetaClassDeclareReservedUnused ( OSData
, 0 );
255 OSMetaClassDeclareReservedUnused ( OSData
, 1 );
256 OSMetaClassDeclareReservedUnused ( OSData
, 2 );
257 OSMetaClassDeclareReservedUnused ( OSData
, 3 );
258 OSMetaClassDeclareReservedUnused ( OSData
, 4 );
259 OSMetaClassDeclareReservedUnused ( OSData
, 5 );
260 OSMetaClassDeclareReservedUnused ( OSData
, 6 );
261 OSMetaClassDeclareReservedUnused ( OSData
, 7 );
264 #endif /* !_OS_OSDATA_H */