Mac Developer Library

Developer

IONetworkData Class Reference

Options
Deployment Target:

On This Page
Language:

IONetworkData

An object that manages a fixed-size named buffer. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.6 and later.
  • Clears the data buffer by filling it with zeroes.

    Declaration

    C++

    virtual bool clearBuffer();

    Return Value

    Returns true if the operation was successful, false otherwise.

    Import Statement

  • Frees the IONetworkData object.

    Declaration

    C++

    virtual void free();

    Import Statement

  • Gets the types of data access supported by this object.

    Declaration

    C++

    virtual UInt32 getAccessTypes() const;

    Return Value

    Returns a mask of supported access types.

    Import Statement

  • Gets a pointer to the data buffer.

    Declaration

    C++

    virtual const void * getBuffer() const;

    Return Value

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

    Import Statement

  • Gets the type of data buffer managed by this object.

    Declaration

    C++

    virtual UInt32 getBufferType() const;

    Return Value

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

    Import Statement

  • Gets a unique OSSymbol key associated with this object.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    virtual Action getNotificationAction() const;

    Return Value

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

    Import Statement

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

    Declaration

    C++

    virtual void * getNotificationParameter() const;

    Return Value

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

    Import Statement

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

    Declaration

    C++

    virtual void * getNotificationTarget() const;

    Return Value

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

    Import Statement

  • Gets the size of the data buffer.

    Declaration

    C++

    virtual UInt32 getSize() const;

    Return Value

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

    Import Statement

  • Initializes an IONetworkData object.

    Declaration

    C++

    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.

    Import Statement

  • An access method that reads from the data buffer.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • An access method that resets the data buffer.

    Declaration

    C++

    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.

    Import Statement

  • Serializes the IONetworkData object.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    virtual void setAccessTypes( UInt32types);

    Parameters

    types

    A mask of access types indicating the supported access types.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • An access method that writes to the data buffer.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

Callbacks

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

    Declaration

    C++

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

    Parameters

    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.

    param

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

    Import Statement

    Availability

    Available in OS X v10.0 through OS X v10.5.

Instance Variables

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;