Chameleon

Chameleon Svn Source Tree

Root/trunk/i386/include/IOKit/network/IONetworkData.h

1/*
2 * Copyright (c) 1998-2008 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * The contents of this file constitute Original Code as defined in and
7 * are subject to the Apple Public Source License Version 1.1 (the
8 * "License"). You may not use this file except in compliance with the
9 * License. Please obtain a copy of the License at
10 * http://www.apple.com/publicsource and read it before using this file.
11 *
12 * This Original Code and all software distributed under the License are
13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
17 * License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * @APPLE_LICENSE_HEADER_END@
21 */
22
23#ifndef _IONETWORKDATA_H
24#define _IONETWORKDATA_H
25
26#define IONetworkParameter IONetworkData // FIXME
27
28/*! @enum NetworkDataAccessTypes
29 @abstract Constants that describe access types.
30 @constant kIONetworkDataAccessTypeRead Read access.
31 @constant kIONetworkDataAccessTypeWrite Write access.
32 @constant kIONetworkDataAccessTypeReset Reset access.
33 @constant kIONetworkDataAccessTypeSerialize Serialization access.
34*/
35
36enum {
37 kIONetworkDataAccessTypeRead = 0x01,
38 kIONetworkDataAccessTypeWrite = 0x02,
39 kIONetworkDataAccessTypeReset = 0x04,
40 kIONetworkDataAccessTypeSerialize = 0x08,
41 kIONetworkDataAccessTypeMask = 0xff
42};
43
44/*! @define kIONetworkDataBasicAccessTypes
45 @discussion The default access types supported by an IONetworkData
46 object. Allow read() and serialize(). */
47
48#define kIONetworkDataBasicAccessTypes \
49 (kIONetworkDataAccessTypeRead | kIONetworkDataAccessTypeSerialize)
50
51/*! @enum NetworkDataBufferTypes
52 @abstract The types of data buffers that can be managed by an IONetworkData object.
53 @constant kIONetworkDataBufferTypeInternal An internal data buffer
54 allocated by the init() method.
55 @constant kIONetworkDataBufferTypeExternal An external (persistent) data
56 buffer.
57 @constant kIONetworkDataBufferTypeNone No data buffer. The only useful
58 action perfomed by an IONetworkData object with this buffer type
59 is to call the access notification handler.
60*/
61
62enum {
63 kIONetworkDataBufferTypeInternal = 0,
64 kIONetworkDataBufferTypeExternal,
65 kIONetworkDataBufferTypeNone
66};
67
68/*! @defined kIONetworkDataBytes
69 @abstract A property of IONetworkData objects.
70 @discussion The kIONetworkDataBytes property is an OSData that describes
71 the data buffer of an IONetworkData object. This property is present
72 only if kIONetworkDataAccessTypeSerialize access is supported.
73*/
74
75#define kIONetworkDataBytes "Data"
76
77/*! @defined kIONetworkDataAccessTypes
78 @abstract A property of IONetworkData objects.
79 @discussion The kIONetworkDataAccessTypes property is an OSNumber that
80 describes the supported access types of an IONetworkData object.
81*/
82
83#define kIONetworkDataAccessTypes "Access Types"
84
85/*! @defined kIONetworkDataSize
86 @abstract A property of IONetworkData objects.
87 @discussion The kIONetworkDataSize property is an OSNumber that
88 describes the size of the data buffer of an IONetworkData object.
89*/
90
91#define kIONetworkDataSize "Size"
92
93#ifdef KERNEL
94
95#include <libkern/c++/OSSymbol.h>
96#include <libkern/c++/OSSerialize.h>
97
98/*! @class IONetworkData
99 @abstract An object that manages a fixed-size named buffer.
100 @discussion An IONetworkData object manages a fixed-size named buffer.
101 This object provides external access methods that can be used to
102 access the contents of the data buffer. In addition, serialization
103 is supported, and therefore this object can be added to a property
104 table to publish the data object. An unique name must be assigned to
105 the object during initialization. An OSSymbol key will be created
106 based on the assigned name, and this key can be used when the object
107 is added to a dictionary.
108
109 The level of access granted to the access methods can be restricted,
110 by specifying a set of supported access types when the object is
111 initialized, or modified later by calling setAccessTypes(). By default,
112 each IONetworkData object created will support serialization, and will
113 also allow its data buffer to be read through the read() access method.
114
115 An access notification handler, in the form of a 'C' function, can
116 be registered to receive a call each time the data buffer is accessed
117 through an access method. Arguments provided to the handler will identify
118 the data object and the type of access that triggered the notification.
119 The handler can therefore perform lazy update of the data buffer until
120 an interested party tries to read or serialize the data. The notification
121 handler can also take over the default action performed by the access
122 methods when the buffer type is set to kIONetworkDataBufferTypeNone.
123 This will prevent the access methods from accessing the data buffer,
124 and allow the handler to override the access protocol.
125
126 This object is primarily used by IONetworkInterface to export interface
127 properties to user space.
128*/
129
130
131class IONetworkData : public OSObject
132{
133 OSDeclareDefaultStructors( IONetworkData )
134
135public:
136
137/*! @typedef Action
138 @abstract Defines a C function that may be called by an IONetworkData object
139 when one of its access methods is called.
140 @param target The target of the notification.
141 @param param A parameter that was provided when the notification
142 handler was registered.
143 @param data The IONetworkData object being accessed, and the
144 sender of the notification.
145 @param accessType A bit will be set indicating the type of access
146 which triggered the notification.
147 @param buffer Pointer to the accessor's buffer. Only valid for
148 read() and write() accesses.
149 @param bufferSize Pointer to the size of the accessor's buffer.
150 @param offset An offset from the start of the data buffer to begin
151 reading or writing.
152*/
153
154 typedef IOReturn (*Action)(void * target,
155 void * param,
156 IONetworkData * data,
157 UInt32 accessType,
158 void * buffer,
159 UInt32 * bufferSize,
160 UInt32 offset);
161
162protected:
163 const OSSymbol * _key; // key associated with this object.
164 UInt32 _access; // supported access types.
165 void * _buffer; // Data buffer.
166 UInt32 _bufType; // buffer type
167 UInt32 _size; // data buffer size.
168 void * _tapTarget; // target for access notification.
169 Action _tapAction; // the function to call.
170 void * _tapParam; // arbitrary notification param.
171
172 struct ExpansionData { };
173 /*! @var reserved
174 Reserved for future use. (Internal use only) */
175 ExpansionData *_reserved;
176
177
178/*! @function free
179 @abstract Frees the IONetworkData object.
180*/
181
182 virtual void free();
183
184/*! @function writeBytes
185 @abstract Writes to the data buffer with data from a source buffer
186 provided by the caller.
187 @param srcBuffer Pointer to a source buffer provided by the caller.
188 @param srcBufferSize The size of the source buffer.
189 @param writeOffset A byte offset from the start of the data buffer
190 to begin writting.
191 @result Returns true if the operation was successful, false otherwise.
192*/
193
194 virtual bool writeBytes(const void * srcBuffer,
195 UInt32 srcBufferSize,
196 UInt32 writeOffset = 0);
197
198/*! @function readBytes
199 @abstract Reads from the data buffer and copies the data to a destination
200 buffer provided by the caller.
201 @param dstBuffer Pointer to the destination buffer.
202 @param dstBufferSize Pointer to an integer containing the size of the
203 destination buffer. And is overwritten by this method with the actual
204 number of bytes copied to the destination buffer.
205 @param readOffset A byte offset from the start of the data buffer
206 to begin reading.
207 @result Returns true if the operation was successful, false otherwise.
208*/
209
210 virtual bool readBytes(void * dstBuffer,
211 UInt32 * dstBufferSize,
212 UInt32 readOffset = 0) const;
213
214/*! @function clearBuffer
215 @abstract Clears the data buffer by filling it with zeroes.
216 @result Returns true if the operation was successful, false otherwise.
217*/
218
219 virtual bool clearBuffer();
220
221public:
222
223/*! @function withInternalBuffer
224 @abstract Factory method that constructs and initializes an
225 IONetworkData object with an internal data buffer.
226 @param name A name to assign to this object.
227 @param bufferSize The number of bytes to allocate for the internal data
228 buffer.
229 @param accessTypes The initial supported access types.
230 @param target The notification target.
231 @param action The notification action.
232 @param param A parameter to pass to the notification action.
233 @result Returns an IONetworkData object on success, or 0 otherwise.
234*/
235
236 static IONetworkData *
237 withInternalBuffer(const char * name,
238 UInt32 bufferSize,
239 UInt32 accessTypes =
240 kIONetworkDataBasicAccessTypes,
241 void * target = 0,
242 Action action = 0,
243 void * param = 0);
244
245/*! @function withExternalBuffer
246 @abstract Factory method that constructs and initializes an
247 IONetworkData object with an external data buffer.
248 @param name A name to assign to this object.
249 @param bufferSize The size of the external data buffer.
250 @param externalBuffer Pointer to the external data buffer.
251 @param accessTypes The initial supported access types.
252 @param target The notification target.
253 @param action The notification action.
254 @param param A parameter to pass to the notification action.
255 @result Returns an IONetworkData object on success, or 0 otherwise.
256*/
257
258 static IONetworkData *
259 withExternalBuffer(const char * name,
260 UInt32 bufferSize,
261 void * externalBuffer,
262 UInt32 accessTypes =
263 kIONetworkDataBasicAccessTypes,
264 void * target = 0,
265 Action action = 0,
266 void * param = 0);
267
268/*! @function withNoBuffer
269 @abstract Factory method that constructs and initializes an
270 IONetworkData object without a data buffer.
271 @discussion The notification handler
272 must intervene when the IONetworkData is accessed.
273 @param name A name to assign to this object.
274 @param bufferSize The size of the phantom data buffer.
275 @param accessTypes The initial supported access types.
276 @param target The notification target.
277 @param action The notification action.
278 @param param A parameter to pass to the notification action.
279 @result Returns an IONetworkData object on success, or 0 otherwise.
280*/
281
282 static IONetworkData * withNoBuffer(const char * name,
283 UInt32 bufferSize,
284 UInt32 accessTypes,
285 void * target,
286 Action action,
287 void * param = 0);
288
289/*! @function init
290 @abstract Initializes an IONetworkData object.
291 @param name A name to assign to this object.
292 @param bufferType The type of buffer associated with this object.
293 @param bufferSize The size of the data buffer.
294 @param externalBuffer Pointer to an external data buffer.
295 @param accessTypes The initial supported access types.
296 Can be later modified by calling setAccessTypes().
297 @param target The notification target.
298 @param action The notification action.
299 @param param A parameter to pass to the notification action.
300 @result Returns true if initialized successfully, false otherwise.
301*/
302
303 virtual bool init(const char * name,
304 UInt32 bufferType,
305 UInt32 bufferSize,
306 void * externalBuffer = 0,
307 UInt32 accessTypes =
308 kIONetworkDataBasicAccessTypes,
309 void * target = 0,
310 Action action = 0,
311 void * param = 0);
312
313/*! @function setAccessTypes
314 @abstract Sets the types of access that are permitted on the data buffer.
315 @param types A mask of access types indicating the supported access
316 types.
317*/
318
319 virtual void setAccessTypes(UInt32 types);
320
321/*! @function setNotificationTarget
322 @abstract Registers a C function to handle access notifications sent
323 from this object.
324 @discussion A notification is sent by an IONetworkData object to the
325 registered notification handler, when an access method is called to
326 modify the contents of the data buffer.
327 @param target The first parameter passed to the notification handler.
328 @param action A pointer to a C function that will handle the notification.
329 If 0, then notification is disabled.
330 @param param An optional parameter passed to the notification handler.
331*/
332
333 virtual void setNotificationTarget(void * target,
334 Action action,
335 void * param = 0);
336
337/*! @function getBuffer
338 @abstract Gets a pointer to the data buffer.
339 @result Returns a pointer to the data buffer. Returns 0 if the buffer type is
340 kIONetworkDataBufferTypeNone.
341*/
342
343 virtual const void * getBuffer() const;
344
345/*! @function getBufferType
346 @abstract Gets the type of data buffer managed by this object.
347 @result Returns a constant that describes the type of the data buffer.
348*/
349
350 virtual UInt32 getBufferType() const;
351
352/*! @function getAccessTypes
353 @abstract Gets the types of data access supported by this object.
354 @result Returns a mask of supported access types.
355*/
356
357 virtual UInt32 getAccessTypes() const;
358
359/*! @function getNotificationTarget
360 @abstract Gets the first parameter that will be passed to the access
361 notification handler.
362 @result Returns the first parameter that will be passed to the access notification
363 handler.
364*/
365
366 virtual void * getNotificationTarget() const;
367
368/*! @function getNotificationAction
369 @abstract Gets the C function that was registered to handle access
370 notifications sent from this object.
371 @result Returns a pointer to a C function, or 0 if notification is disabled.
372*/
373
374 virtual Action getNotificationAction() const;
375
376/*! @function getNotificationParameter
377 @abstract Gets the parameter that will be passed to the access
378 notification handler.
379 @result Returns the parameter that will be passed to the access notification
380 handler.
381*/
382
383 virtual void * getNotificationParameter() const;
384
385/*! @function getKey
386 @abstract Gets a unique OSSymbol key associated with this object.
387 @discussion During initialization, IONetworkData will create an
388 OSSymbol key based on its assigned name.
389 @result Returns an OSSymbol key that was generated from the name assigned to
390 this object.
391*/
392
393 virtual const OSSymbol * getKey() const;
394
395/*! @function getSize
396 @abstract Gets the size of the data buffer.
397 @result Returns the size of the data buffer managed by this object in bytes.
398*/
399
400 virtual UInt32 getSize() const;
401
402/*! @function reset
403 @abstract An access method that resets the data buffer.
404 @discussion This method handles an external request to reset the data buffer.
405 If notification is enabled, then the notification handler is called
406 after the data buffer has been cleared.
407 @result Returns kIOReturnSuccess on success,
408 kIOReturnNotWritable if reset access is not permitted,
409 or an error from the notification handler.
410*/
411
412 virtual IOReturn reset();
413
414/*! @function read
415 @abstract An access method that reads from the data buffer.
416 @discussion This method handles an external request to read from the data buffer
417 and copy it to the destination buffer provided by the accessor.
418 If notification is enabled, then the notification handler is called
419 before the data buffer is copied to the destination buffer. The
420 notification handler may use this opportunity to intervene and
421 to update the contents of the data buffer.
422 @param dstBuffer Pointer to the destination buffer.
423 @param dstBufferSize Pointer to an integer containing the size of the
424 destination buffer. And is overwritten by this method to the actual number
425 of bytes copied to the destination buffer.
426 @param readOffset An offset from the start of the source data buffer to
427 begin reading.
428 @result Returns kIOReturnSuccess on success,
429 kIOReturnBadArgument if any of the arguments provided is invalid,
430 kIOReturnNotReadable if read access is not permitted,
431 or an error from the notification handler.
432*/
433
434 virtual IOReturn read(void * dstBuffer,
435 UInt32 * dstBufferSize,
436 UInt32 readOffset = 0);
437
438/*! @function write
439 @abstract An access method that writes to the data buffer.
440 @discussion This method handles an external request to write to the data buffer
441 from a source buffer provided by the accessor. After checking that
442 the data object supports write accesses, the data buffer is updated
443 if it exists. Then the registered notification handler is called.
444 @param srcBuffer Pointer to the source buffer.
445 @param srcBufferSize The number of bytes to write to the data buffer.
446 @param writeOffset An offset from the start of the destination data buffer
447 to begin writing.
448 @result Returns kIOReturnSuccess on success,
449 kIOReturnBadArgument if any of the arguments provided is invalid,
450 kIOReturnNotWritable if write access is not permitted,
451 or an error from the notification handler.
452*/
453
454 virtual IOReturn write(void * srcBuffer,
455 UInt32 srcBufferSize,
456 UInt32 writeOffset = 0);
457
458/*! @function serialize
459 @abstract Serializes the IONetworkData object.
460 @discussion If notification is enabled, then the notification
461 handler is called just before the data buffer is serialized.
462 @param s An OSSerialize object.
463 @result Returns true on success, false otherwise.
464*/
465
466 virtual bool serialize(OSSerialize * s) const;
467
468 // Virtual function padding
469 OSMetaClassDeclareReservedUnused( IONetworkData, 0);
470 OSMetaClassDeclareReservedUnused( IONetworkData, 1);
471 OSMetaClassDeclareReservedUnused( IONetworkData, 2);
472 OSMetaClassDeclareReservedUnused( IONetworkData, 3);
473};
474
475#endif /* KERNEL */
476
477#endif /* !_IONETWORKDATA_H */
478

Archive Download this file

Revision: 881