![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IONetworkData.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / network|
Return to IONetworkData.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / network |
1.1 root 1: /*
2: * Copyright (c) 1998-2000 Apple Computer, 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: * Copyright (c) 1998 Apple Computer, Inc. All rights reserved.
24: *
25: * IONetworkData.h
26: *
27: * HISTORY
28: * 21-Apr-1999 Joe Liu (jliu) created.
29: *
30: */
31:
32: #ifndef _IONETWORKDATA_H
33: #define _IONETWORKDATA_H
34:
35: #define IONetworkParameter IONetworkData
36:
37: /*! @enum IONDAccessFlags
38: @discussion Flags to encode access types, and other flags
39: used by the access methods.
40: @constant kIONDAccessTypeRead read access type.
41: @constant kIONDAccessTypeWrite write access type.
42: @constant kIONDAccessTypeReset reset access type.
43: @constant kIONDAccessTypeSerialize serialize access type.
44: @constant kIONDAccessNoBufferAccess The data buffer
45: cannot be accessed through the access methods. Buffer serialization
46: is also disabled. However, the notification handler will continue
47: to be called for supported access types. */
48:
49: enum IONDAccessFlags {
50: kIONDAccessTypeRead = 0x01,
51: kIONDAccessTypeWrite = 0x02,
52: kIONDAccessTypeReset = 0x04,
53: kIONDAccessTypeSerialize = 0x08,
54: kIONDAccessTypeMask = 0xff,
55:
56: kIONDAccessNoBufferAccess = 0x100,
57: };
58:
59: /*! @define kIONDBasicAccessTypes
60: @discussion The default access types supported by an IONetworkData
61: object. Allow read() and serialize(). */
62:
63: #define kIONDBasicAccessTypes \
64: (kIONDAccessTypeRead | kIONDAccessTypeSerialize)
65:
66: /*! @define kIONDImmutableAccessFlags
67: @discussion Access flags that cannot be changed by setAccessFlags(),
68: after the object has been initialized. */
69:
70: #define kIONDImmutableAccessFlags 0
71:
72: #ifdef KERNEL
73:
74: #include <libkern/c++/OSData.h>
75: #include <libkern/c++/OSSymbol.h>
76: #include <libkern/c++/OSSerialize.h>
77:
78: /*! @class IONetworkData : public OSData
79: An IONetworkData manages a fixed-capacity named buffer.
80: This class provide external access methods that can be called by
81: an IOUserClient to allow user space access to the data buffer.
82: In addition, serialization is supported, and therefore the object
83: can be added to a property table to publish the data object.
84: An unique name must be assigned to the object during initialization.
85: An OSSymbol key will be created based on the assigned name, and this
86: key should be used when the object is added to a dictionary.
87:
88: The level of access granted to the access methods can be controlled,
89: by specifying a default set of access flags when the object is
90: initialized, or modified later by calling setAccessFlags(). By
91: default, each IONetworkData object created will support serialization,
92: and will also allow its data buffer to be read through the read()
93: access method.
94:
95: A notification handler, in the form of a C++ function pointer, can
96: be registered to receive a call each time the data buffer is accessed
97: through an access method. Arguments provided will identify the data
98: object and the type of access that triggered the notification.
99: The handler can therefore perform lazy update of the data buffer
100: until an interested party tries to read the data.
101: The notification handler can also take over the default action performed
102: by the access methods when the kIONDAccessNoBufferAccess flag is set.
103: This will prevent the access methods from accessing the data buffer,
104: and allow the handler to override the access protocol.
105:
106: This object is used by IONetworkInterface to export statistics
107: counters to user space. */
108:
109:
110: class IONetworkData : public OSData
111: {
112: OSDeclareDefaultStructors(IONetworkData)
113:
114: public:
115:
116: /*! @typedef Action
117: Defines the prototype of the notification handler that is called
118: when the data buffer is accessed through an access method.
119: @param data The IONetworkData object being accessed
120: (the sender of the notification).
121: @param accessType A bit will be set indicating a particular
122: access type.
123: @param arg An action argument.
124: @param buffer Pointer to the client buffer for read() and write()
125: accesses.
126: @param bufSize Pointer to the size of the client buffer. */
127:
128: typedef IOReturn (OSObject::*Action)(IONetworkData * data,
129: UInt32 accessType,
130: void * arg,
131: void * buffer,
132: UInt32 * bufSize);
133:
134: protected:
135: const OSSymbol * _key; // key associated with this object.
136: UInt32 _access; // access flags.
137: UInt _capacity; // data buffer capacity.
138: OSObject * _tapTarget; // a target for access notification.
139: Action _tapAction; // the target method to call.
140: void * _tapArg; // arbitrary target argument.
141:
142: /*! @function free
143: @abstract Free the IONetworkData instance. */
144:
145: virtual void free();
146:
147: public:
148:
149: /*! @function initialize
150: @abstract IONetworkData class initializer. */
151:
152: static void initialize();
153:
154: /*! @function withName
155: @abstract Factory method that will construct and initialize an
156: IONetworkData instance.
157: @param name A name assigned to this object.
158: @param capacity Capacity of the data buffer.
159: @param buffer Pointer to an external data buffer. If 0,
160: then an internal buffer shall be allocated.
161: @param accessFlags Access flags.
162: Can be later modified by calling setAccessFlags().
163: @param target Notification target. The target will be notified
164: when IONetworkData receives a call to one of its
165: access methods. If 0, then notification is disabled.
166: @param action Notification action. If 0, then notification is
167: disabled.
168: @param arg An argument to passed to the notification
169: action when it is called.
170: @result An IONetworkData instance on success, or 0 otherwise. */
171:
172: static IONetworkData * withName(
173: const char * name,
174: UInt32 capacity,
175: void * buffer = 0,
176: UInt32 accessFlags = kIONDBasicAccessTypes,
177: OSObject * target = 0,
178: Action action = 0,
179: void * arg = 0);
180:
181: /*! @function init
182: @abstract Initialize an IONetworkData instance.
183: @param name A name assigned to this object.
184: @param capacity Capacity of the data buffer.
185: @param buffer Pointer to an external data buffer. If 0,
186: then an internal buffer shall be allocated.
187: @param accessFlags Access flags.
188: Can be later modified by calling setAccessFlags().
189: @param target Notification target. The target will be notified
190: when IONetworkData receives a call to one of its
191: access methods. If 0, then notification is disabled.
192: @param action Notification action. If 0, then notification is
193: disabled.
194: @param arg An argument to passed to the notification
195: action when it is called.
196: @result true if initialized successfully, false otherwise. */
197:
198: virtual bool initWithName(const char * name,
199: UInt32 capacity,
200: void * buffer = 0,
201: UInt32 accessFlags = kIONDBasicAccessTypes,
202: OSObject * target = 0,
203: Action action = 0,
204: void * arg = 0);
205:
206: /*! @function setAccessFlags
207: @abstract Change the access flags.
208: @param accessFlags A bitfield of access flag bits.
209: See IONDAccessFlags enum. */
210:
211: virtual void setAccessFlags(UInt32 accessFlags);
212:
213: /*! @function setNotificationTarget
214: @abstract Register a target/action to handle access notification.
215: @discussion A notification is sent by an IONetworkData to the registered
216: notification handler when an access method is called.
217: @param target The target object that implements the notification action.
218: If 0, then notification will be disabled.
219: @param action The notification action.
220: If 0, then notification will be disabled.
221: @param arg An optional argument passed to the notification handler. */
222:
223: virtual void setNotificationTarget(OSObject * target,
224: Action action,
225: void * arg = 0);
226:
227: /*! @function getBuffer
228: @result A pointer to the data buffer. */
229:
230: virtual const void * getBuffer() const;
231:
232: /*! @function getAccessFlags
233: @result The access flags. */
234:
235: virtual UInt32 getAccessFlags() const;
236:
237: /*! @function getTarget
238: @result The notification target. */
239:
240: virtual OSObject * getTarget() const;
241:
242: /*! @function getAction
243: @result The notification action. */
244:
245: virtual Action getAction() const;
246:
247: /*! @function getArgument
248: @result The optional notification argument. */
249:
250: virtual void * getArgument() const;
251:
252: /*! @function getKey
253: @abstract Get an OSSymbol key associated with this IONetworkData
254: instance.
255: @discussion During initialization, IONetworkData will create an
256: OSSymbol key based on its assigned name.
257: @result An OSSymbol key generated from the assigned name. */
258:
259: virtual const OSSymbol * getKey() const;
260:
261: /*! @function getCapacity
262: @abstract Override the getCapacity() method inherited from OSData.
263: @discussion This method overrides the implementation in OSData
264: in order to report the capacity for both internal or external
265: data buffers.
266: @result The capacity of the data buffer in bytes. */
267:
268: virtual UInt getCapacity() const;
269:
270: /*! @function setBytes
271: @abstract Update the data buffer from a source buffer provided by the
272: caller.
273: @param bytes Pointer to a source buffer provided by the caller.
274: @param inLength Length of the source buffer, or the amount of data
275: to copy to the data buffer. The length provided must
276: be smaller than or equal to the capacity of the object.
277: @result true if the length of the source buffer is within limits,
278: and the source buffer was copied, false otherwise. */
279:
280: virtual bool setBytes(const void * bytes, UInt inLength);
281:
282: /*! @function setLength
283: @abstract Set a new data buffer length to indicate the amount of
284: valid data in the data buffer.
285: @param inLength Length of the data buffer in bytes. This must be
286: smaller than or equal to the capacity of the data object.
287: @result true if the length provided was accepted. */
288:
289: virtual bool setLength(UInt inLength);
290:
291: /*! @function copyBytes
292: @abstract Copy the data buffer (with length bytes) to a destination
293: buffer provided by the caller.
294: @param bytes Pointer to a destination buffer.
295: @param inOutLength The caller must initialize the integer value pointed
296: by inOutLength with the size of the destination buffer before the call.
297: This method will overwrite it with the number of bytes copied.
298: @result true if the destination buffer is larger than or equal to the
299: length of the data buffer, false otherwise. */
300:
301: virtual bool copyBytes(void * bytes, UInt * inOutLength) const;
302:
303: /*! @function clearBytes
304: @abstract Clear the entire data buffer and fill it with zeroes.
305: @result true if the buffer was cleared, false otherwise. */
306:
307: virtual bool clearBytes();
308:
309: /*! @function reset
310: @abstract An access method to reset the data buffer.
311: @discussion Handle an external request to reset the data buffer.
312: If notication is enabled, then the notification handler is called
313: after the data buffer has been cleared.
314: @result kIOReturnNotWritable if reset access is not allowed,
315: kIOReturnSuccess otherwise. If a notification handler is called,
316: and it returns an error code, then that error is returned. */
317:
318: virtual IOReturn reset();
319:
320: /*! @function read
321: @abstract An access method to read from the data buffer.
322: @discussion Handle an external request to read from the data buffer
323: and copy it to the destination buffer provided. If notification is
324: enabled, then the notification handler is called before the data buffer
325: is copied to the destination buffer. The notification handler may use
326: this opportunity to update the contents of the data buffer.
327: @param inBuffer Pointer to the destination buffer.
328: @param inOutSize Pointer to an integer containing the size of the
329: destination buffer before the call. Overwritten by this method to
330: the actual number of bytes copied to the destination buffer.
331: @result kIOReturnSuccess on success,
332: kIOReturnBadArgument if an argument provided is invalid,
333: kIOReturnNoSpace if the destination buffer is too small,
334: kIOReturnNotReadable if read access is not permitted,
335: or an error from the notification handler. */
336:
337: virtual IOReturn read(void * inBuffer, UInt * inOutSize);
338:
339: /*! @function write
340: @abstract An access method to write to the data buffer.
341: @discussion Handle an external request to write to the data buffer
342: from a source buffer provided. If notification is enabled, then
343: the notification handler is called after the source buffer has
344: been copied to the data buffer.
345: @param inBuffer Pointer to the source buffer.
346: @param size Size of the source buffer in bytes.
347: @result kIOReturnSuccess on success,
348: kIOReturnBadArgument if an argument provided is invalid,
349: kIOReturnNoSpace if the source buffer is too big,
350: kIOReturnNotWritable if write access is not permitted,
351: or an error from the notification handler. */
352:
353: virtual IOReturn write(void * inBuffer, UInt size);
354:
355: /*! @function serialize
356: @abstract Serialize the object, including the data buffer.
357: @discussion If notification is enabled, then the notification
358: handler is called just before the data buffer is serialized.
359: @param s An OSSerialize object.
360: @result true on success, false otherwise. */
361:
362: virtual bool serialize(OSSerialize * s) const;
363: };
364:
365: #endif /* KERNEL */
366:
367: #endif /* !_IONETWORKDATA_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.