Return to IONetworkData.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / network

Annotation of XNU/iokit/IOKit/network/IONetworkData.h, revision 1.1

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.