ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IONetworkData

Inherits from:	OSObject
Declared In:	IONetworkData.h

Overview

An object that manages a fixed-size named buffer.

Discussion

An IONetworkData object manages a fixed-size named buffer. This object provides external access methods that can be used to access the contents of the data buffer. In addition, serialization is supported, and therefore this object can be added to a property table to publish the data object. An unique name must be assigned to the object during initialization. An OSSymbol key will be created based on the assigned name, and this key can be used when the object is added to a dictionary.

The level of access granted to the access methods can be restricted, by specifying a set of supported access types when the object is initialized, or modified later by calling setAccessTypes(). By default, each IONetworkData object created will support serialization, and will also allow its data buffer to be read through the read() access method.

An access notification handler, in the form of a 'C' function, can be registered to receive a call each time the data buffer is accessed through an access method. Arguments provided to the handler will identify the data object and the type of access that triggered the notification. The handler can therefore perform lazy update of the data buffer until an interested party tries to read or serialize the data. The notification handler can also take over the default action performed by the access methods when the buffer type is set to kIONetworkDataBufferTypeNone. This will prevent the access methods from accessing the data buffer, and allow the handler to override the access protocol.

This object is primarily used by IONetworkInterface to export interface properties to user space.

Functions

clearBuffer: Clears the data buffer by filling it with zeroes.
free: Frees the IONetworkData object.
getAccessTypes: Gets the types of data access supported by this object.
getBuffer: Gets a pointer to the data buffer.
getBufferType: Gets the type of data buffer managed by this object.
getKey: Gets a unique OSSymbol key associated with this object.
getNotificationAction: Gets the C function that was registered to handle access notifications sent from this object.
getNotificationParameter: Gets the parameter that will be passed to the access notification handler.
getNotificationTarget: Gets the first parameter that will be passed to the access notification handler.
getSize: Gets the size of the data buffer.
init: Initializes an IONetworkData object.
read: An access method that reads from the data buffer.
readBytes: Reads from the data buffer and copies the data to a destination buffer provided by the caller.
reset: An access method that resets the data buffer.
serialize: Serializes the IONetworkData object.
setAccessTypes: Sets the types of access that are permitted on the data buffer.
setNotificationTarget: Registers a C function to handle access notifications sent from this object.
withExternalBuffer: Factory method that constructs and initializes an IONetworkData object with an external data buffer.
withInternalBuffer: Factory method that constructs and initializes an IONetworkData object with an internal data buffer.
withNoBuffer: Factory method that constructs and initializes an IONetworkData object without a data buffer.
write: An access method that writes to the data buffer.
writeBytes: Writes to the data buffer with data from a source buffer provided by the caller.

clearBuffer

Clears the data buffer by filling it with zeroes.

protected

virtual bool clearBuffer();

Return Value

Returns true if the operation was successful, false otherwise.

free

Frees the IONetworkData object.

protected

virtual void free();

getAccessTypes

Gets the types of data access supported by this object.

public

virtual UInt32 getAccessTypes() const;

Return Value

Returns a mask of supported access types.

getBuffer

Gets a pointer to the data buffer.

public

virtual const void * getBuffer() const;

Return Value

Returns a pointer to the data buffer. Returns 0 if the buffer type is kIONetworkDataBufferTypeNone.

getBufferType

Gets the type of data buffer managed by this object.

public

virtual UInt32 getBufferType() const;

Return Value

Returns a constant that describes the type of the data buffer.

getKey

Gets a unique OSSymbol key associated with this object.

public

virtual const OSSymbol * getKey() const;

Return Value

Returns an OSSymbol key that was generated from the name assigned to this object.

Discussion

During initialization, IONetworkData will create an OSSymbol key based on its assigned name.

getNotificationAction

Gets the C function that was registered to handle access notifications sent from this object.

public

virtual Action getNotificationAction() const;

Return Value

Returns a pointer to a C function, or 0 if notification is disabled.

getNotificationParameter

Gets the parameter that will be passed to the access notification handler.

public

virtual void * getNotificationParameter() const;

Return Value

Returns the parameter that will be passed to the access notification handler.

getNotificationTarget

Gets the first parameter that will be passed to the access notification handler.

public

virtual void * getNotificationTarget() const;

Return Value

Returns the first parameter that will be passed to the access notification handler.

getSize

Gets the size of the data buffer.

public

virtual UInt32 getSize() const;

Return Value

Returns the size of the data buffer managed by this object in bytes.

init

Initializes an IONetworkData object.

public

virtual bool init(
    const char * name, 
    UInt32 bufferType, 
    UInt32 bufferSize, 
    void * externalBuffer = 0, 
    UInt32 accessTypes =   (
        kIONetworkDataAccessTypeRead | kIONetworkDataAccessTypeSerialize), 
    void *target = 0, 
    Action action = 0, 
    void *param = 0);

Parameters

name: A name to assign to this object.
bufferType: The type of buffer associated with this object.
bufferSize: The size of the data buffer.
externalBuffer: Pointer to an external data buffer.
accessTypes: The initial supported access types. Can be later modified by calling setAccessTypes().
target: The notification target.
action: The notification action.
param: A parameter to pass to the notification action.

Return Value

Returns true if initialized successfully, false otherwise.

read

An access method that reads from the data buffer.

public

virtual IOReturn read(
    void *dstBuffer, 
    UInt32 *dstBufferSize, 
    UInt32 readOffset = 0);

Parameters

dstBuffer: Pointer to the destination buffer.
dstBufferSize: Pointer to an integer containing the size of the destination buffer. And is overwritten by this method to the actual number of bytes copied to the destination buffer.
readOffset: An offset from the start of the source data buffer to begin reading.

Return Value

Returns kIOReturnSuccess on success, kIOReturnBadArgument if any of the arguments provided is invalid, kIOReturnNotReadable if read access is not permitted, or an error from the notification handler.

Discussion

This method handles an external request to read from the data buffer and copy it to the destination buffer provided by the accessor. If notification is enabled, then the notification handler is called before the data buffer is copied to the destination buffer. The notification handler may use this opportunity to intervene and to update the contents of the data buffer.

readBytes

Reads from the data buffer and copies the data to a destination buffer provided by the caller.

protected

virtual bool readBytes(
    void *dstBuffer, 
    UInt32 *dstBufferSize, 
    UInt32 readOffset = 0) const;

Parameters

dstBuffer: Pointer to the destination buffer.
dstBufferSize: Pointer to an integer containing the size of the destination buffer. And is overwritten by this method with the actual number of bytes copied to the destination buffer.
readOffset: A byte offset from the start of the data buffer to begin reading.

Return Value

Returns true if the operation was successful, false otherwise.

reset

An access method that resets the data buffer.

public

virtual IOReturn reset();

Return Value

Returns kIOReturnSuccess on success, kIOReturnNotWritable if reset access is not permitted, or an error from the notification handler.

Discussion

This method handles an external request to reset the data buffer. If notification is enabled, then the notification handler is called after the data buffer has been cleared.

serialize

Serializes the IONetworkData object.

public

virtual bool serialize(
    OSSerialize *s) const;

Parameters

s: An OSSerialize object.

Return Value

Returns true on success, false otherwise.

Discussion

If notification is enabled, then the notification handler is called just before the data buffer is serialized.

setAccessTypes

Sets the types of access that are permitted on the data buffer.

public

virtual void setAccessTypes(
    UInt32 types);

Parameters

types: A mask of access types indicating the supported access types.

setNotificationTarget

Registers a C function to handle access notifications sent from this object.

public

virtual void setNotificationTarget(
    void *target, 
    Action action, 
    void *param = 0);

Parameters

target: The first parameter passed to the notification handler.
action: A pointer to a C function that will handle the notification. If 0, then notification is disabled.
param: An optional parameter passed to the notification handler.

Discussion

A notification is sent by an IONetworkData object to the registered notification handler, when an access method is called to modify the contents of the data buffer.

withExternalBuffer

Factory method that constructs and initializes an IONetworkData object with an external data buffer.

public

static IONetworkData * withExternalBuffer(
    const char * name, 
    UInt32 bufferSize, 
    void * externalBuffer, 
    UInt32 accessTypes =   (kIONetworkDataAccessTypeRead | kIONetworkDataAccessTypeSerialize), 
    void * target = 0, 
    Action action = 0, 
    void *param = 0);

Parameters

name: A name to assign to this object.
bufferSize: The size of the external data buffer.
externalBuffer: Pointer to the external data buffer.
accessTypes: The initial supported access types.
target: The notification target.
action: The notification action.
param: A parameter to pass to the notification action.

Return Value

Returns an IONetworkData object on success, or 0 otherwise.

withInternalBuffer

Factory method that constructs and initializes an IONetworkData object with an internal data buffer.

public

static IONetworkData * withInternalBuffer(
    const char * name, 
    UInt32 bufferSize, 
    UInt32 accessTypes =   (kIONetworkDataAccessTypeRead | kIONetworkDataAccessTypeSerialize), 
    void * target = 0, 
    Action action = 0, 
    void *param = 0);

Parameters

name: A name to assign to this object.
bufferSize: The number of bytes to allocate for the internal data buffer.
accessTypes: The initial supported access types.
target: The notification target.
action: The notification action.
param: A parameter to pass to the notification action.

Return Value

Returns an IONetworkData object on success, or 0 otherwise.

withNoBuffer

Factory method that constructs and initializes an IONetworkData object without a data buffer.

public

static IONetworkData * withNoBuffer(
    const char * name, 
    UInt32 bufferSize, 
    UInt32 accessTypes, 
    void * target, 
    Action action, 
    void * param = 0);

Parameters

name: A name to assign to this object.
bufferSize: The size of the phantom data buffer.
accessTypes: The initial supported access types.
target: The notification target.
action: The notification action.
param: A parameter to pass to the notification action.

Return Value

Returns an IONetworkData object on success, or 0 otherwise.

Discussion

The notification handler must intervene when the IONetworkData is accessed.

write

An access method that writes to the data buffer.

public

virtual IOReturn write(
    void *srcBuffer, 
    UInt32 srcBufferSize, 
    UInt32 writeOffset = 0);

Parameters

srcBuffer: Pointer to the source buffer.
srcBufferSize: The number of bytes to write to the data buffer.
writeOffset: An offset from the start of the destination data buffer to begin writing.

Return Value

Returns kIOReturnSuccess on success, kIOReturnBadArgument if any of the arguments provided is invalid, kIOReturnNotWritable if write access is not permitted, or an error from the notification handler.

Discussion

This method handles an external request to write to the data buffer from a source buffer provided by the accessor. After checking that the data object supports write accesses, the data buffer is updated if it exists. Then the registered notification handler is called.

writeBytes

Writes to the data buffer with data from a source buffer provided by the caller.

protected

virtual bool writeBytes(
    const void * srcBuffer, 
    UInt32 srcBufferSize, 
    UInt32 writeOffset = 0);

Parameters

srcBuffer: Pointer to a source buffer provided by the caller.
srcBufferSize: The size of the source buffer.
writeOffset: A byte offset from the start of the data buffer to begin writting.

Return Value

Returns true if the operation was successful, false otherwise.

Typedefs

Action

Defines a C function that may be called by an IONetworkData object when one of its access methods is called.

public

typedef IOReturn ( *Action)(
    void *target, 
    void *param, 
    IONetworkData *data, 
    UInt32 accessType, 
    void *buffer, 
    UInt32 *bufferSize, 
    UInt32 offset);

Fields

target: The target of the notification.
data: The IONetworkData object being accessed, and the sender of the notification.
accessType: A bit will be set indicating the type of access which triggered the notification.
buffer: Pointer to the accessor's buffer. Only valid for read() and write() accesses.
bufferSize: Pointer to the size of the accessor's buffer.
offset: An offset from the start of the data buffer to begin reading or writing.

Fields

param

A parameter that was provided when the notification handler was registered.

Member Data

_reserved

See Also:

reserved

protected

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

reserved

See Also:

_reserved

protected

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19