Root/
Source at commit 1902 created 12 years 4 months ago. By ifabio, Package: - Added fa.po: Farsi Language (44% Completed) - Update ro.po: Russian Language (93% Completed) | |
---|---|
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 | ␊ |
36 | enum {␊ |
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 | ␊ |
62 | enum {␊ |
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 | ␊ |
131 | class IONetworkData : public OSObject␊ |
132 | {␊ |
133 | OSDeclareDefaultStructors( IONetworkData )␊ |
134 | ␊ |
135 | public:␊ |
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 | ␊ |
162 | protected:␊ |
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 | ␊ |
221 | public:␊ |
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 |