iokit/IOKit/network/IONetworkData.h

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