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