Mac Developer Library

Developer

IONetworkInterface Class Reference

Options
Deployment Target:

On This Page
Language:

IONetworkInterface

Inheritance


  • IONetworkInterface

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.6 and later.

Abstract class that manages the connection between an IONetworkController and the data link interface layer.

An IONetworkInterface object manages the connection between an IONetworkController and the data link interface layer (DLIL). All interactions between the controller and DLIL must go through an interface object. Any data structures that are required by DLIL for a particular interface type shall be allocated and mantained by the interface object. IONetworkInterface is an abstract class that must be extended by a concrete subclass to specialize for a particular network type.

Although most drivers will allocate a single interface object, it is possible for multiple interfaces to be attached to a single controller. This controller driver will be responsible for arbitrating access among its multiple interface clients.

IONetworkInterface also maintains a dictionary of IONetworkData objects containing statistics structures. Controller drivers can ask for a particular data object by name and update the statistics counters within directly. This dictionary is added to the interface's property table and is visible outside of the kernel.

  • Adds an IONetworkData object to the interface.

    Declaration

    C++

    virtual bool addNetworkData( IONetworkData *aData );

    Parameters

    aData

    The IONetworkData object.

    Return Value

    Returns true if the object was added, false otherwise.

    Discussion

    The IONetworkData object is added to a collection using the key from IONetworkData::getKey()

  • Attach the network interface to the BSD data link layer.

    Declaration

    C++

    virtual IOReturn attachToDataLinkLayer( IOOptionBitsoptions, void *parameter );

    Parameters

    options

    Options for the attach call. None are currently defined.

    parameter

    Parameter for the attach call. Not currently used.

    Return Value

    Returns kIOReturnSuccess on success.

    Discussion

    This method is called internally to attach the network interface to the BSD data link layer, after an unit number has been assigned. The calling context is not synchronized against the driver's work loop. Subclasses may override this method to perform additional setup before the network stack attach. The getIfnet() method will return the BSD interface being attached.

  • Discards all packets in the input queue.

    Declaration

    C++

    virtual UInt32 clearInputQueue( void );

    Return Value

    Returns the number of packets freed.

    Discussion

    This method removes all packets from the input queue and releases them back to the free mbuf pool. It is unusual for a driver to call this method.

  • Handles a notification that the network controller servicing this interface object has transitioned to a new power state.

    Declaration

    C++

    virtual IOReturn controllerDidChangePowerState( IONetworkController *controller, IOPMPowerFlagsflags, UInt32stateNumber, IOService *policyMaker );

    Parameters

    controller

    The network controller object.

    flags

    Flags that describe the capability of the controller in the new power state.

    stateNumber

    An index to a state in the network controller's power state array that the controller has switched to.

    policyMaker

    A reference to the network controller's policy-maker, and is also the originator of this notification.

    Return Value

    The return value is always kIOReturnSuccess.

  • Sends a notification that the interface has opened the network controller.

    Declaration

    C++

    virtual bool controllerDidOpen( IONetworkController *controller );

    Parameters

    controller

    The controller that was opened.

    Return Value

    Must return true in order for handleOpen() to accept the client open. If the return is false, then the controller will be closed and the client open will fail.

    Discussion

    This method is called by handleOpen() to notify subclasses that the controller was opened. The open on the controller occurs when the interface receives the initial open request from a client. Subclasses can override this method and inspect the controller before allowing the client open. This method is called with the arbitration lock held, hence issuing I/O to the controller must be avoided to eliminate the possibility of a deadlock.

  • Handles a notification that the network controller servicing this interface object will transition to a new power state.

    Declaration

    C++

    virtual IOReturn controllerWillChangePowerState( IONetworkController *controller, IOPMPowerFlagsflags, UInt32stateNumber, IOService *policyMaker );

    Parameters

    controller

    The network controller object.

    flags

    Flags that describe the capability of the controller in the new power state.

    stateNumber

    An index to a state in the network controller's power state array that the controller is switching to.

    policyMaker

    A reference to the network controller's policy-maker, and is also the originator of this notification.

    Return Value

    The return value is always kIOReturnSuccess.

  • Sends a notification that the interface will close the network controller.

    Declaration

    C++

    virtual void controllerWillClose( IONetworkController *controller );

    Parameters

    controller

    The controller that is about to be closed.

    Discussion

    This method is called by handleClose() after receiving a close from the last interface client, and just before the controller is closed. Subclasses can override this method to perform any cleanup action before the controller is closed. This method is called with the arbitration lock held, hence issuing I/O to the controller should be avoided to eliminate the possibility of a deadlock.

  • Tells the IONetworkData that this interface will be used by the debugger.

    Declaration

    C++

    void debuggerRegistered( void );

  • Detach the network interface from the BSD data link layer.

    Declaration

    C++

    virtual void detachFromDataLinkLayer( IOOptionBitsoptions, void *parameter );

    Parameters

    options

    Options for the detach call. None are currently defined.

    parameter

    Parameter for the detach call. Not currently used.

    Discussion

    This method is called internally to detach the network interface from the BSD data link layer, after the interface has been terminated and before the last client close. This method will block until the detach operation is complete. The calling context is not synchronized against the driver's work loop. Subclasses may override this method to perform additional cleanup before or after detaching from the network stack. The getIfnet() method will return NULL after detach.

  • Feed received packets to the BPF

    Declaration

    C++

    virtual void feedPacketInputTap( mbuf_t );

    Parameters

    mbuf_t

    Pointer to the input packet.

    Discussion

    This function is called internally to send input packets to the BPF input tap when it is enabled. Subclasses are not expected to override this method.

  • Feed output packets to the BPF

    Declaration

    C++

    virtual void feedPacketOutputTap( mbuf_t );

    Parameters

    mbuf_t

    Pointer to the output packet.

    Discussion

    This function is called internally to send output packets to the BPF output tap when it is enabled. Subclasses are not expected to override this method.

  • Submit all packets held in the input queue to the network stack.

    Declaration

    C++

    virtual UInt32 flushInputQueue( void );

    Return Value

    Returns the number of packets that were submitted to the network stack. Returns zero if the queue was empty.

    Discussion

    Allow drivers to remove all packets from the input queue and submit them to the network stack. This method should be used in concert with the inputPacket() method, to flush the input queue after queueing a number of received packets.

  • Frees the IONetworkInterface object.

    Declaration

    C++

    virtual void free( void );

    Discussion

    Resource allocated by init() are released, and clearInputQueue() is called to ensure that the input queue is empty. The interface should have already detached from the network stack.

  • Gets the IONetworkController object that created this interface.

    Declaration

    C++

    virtual IONetworkController * getController( void ) const;

    Return Value

    Returns the parent IONetworkController object.

    Discussion

    The controller object passed to init() will be retained until the interface closes the controller. Subclasses can safely call this method before the controller is closed.

  • Gets the current interface eflags.

    Declaration

    C++

    virtual UInt32 getExtraFlags( void ) const;

    Return Value

    Returns the value of the interface eflags.

    Discussion

    This method calls ifnet_eflags and returns the current interface eflags.

  • Gets the current interface flags.

    Declaration

    C++

    virtual UInt16 getFlags( void ) const;

    Return Value

    Returns the interface flags.

    Discussion

    This method calls ifnet_flags and returns the current interface flags.

  • Returns the ifnet_t allocated by the interface object.

    Declaration

    C++

    virtual ifnet_t getIfnet( void ) const;

    Return Value

    Returns the ifnet_t after the interface has attached to the network stack and before the interface is detached, otherwise returns NULL.

    Discussion

    Gets the interface's ifnet_t, which is managed primarily by IONetworkInterface, however subclasses or drivers can use this method to obtain a reference to the ifnet_t for interface KPI calls.

  • Reports the current state of the interface object.

    Declaration

    C++

    virtual UInt32 getInterfaceState( void ) const;

    Return Value

    Returns the current interface state flags.

  • Gets the interface type.

    Declaration

    C++

    virtual UInt8 getInterfaceType( void ) const;

    Return Value

    Returns a constant defined in bsd/net/if_types.h that describes the interface type.

    Discussion

    This method returns the interface type previously set by setInterfaceType.

  • Gets the maximum transfer unit for this interface.

    Declaration

    C++

    virtual UInt32 getMaxTransferUnit( void ) const;

    Return Value

    Returns the interface MTU size in bytes.

    Discussion

    This method calls ifnet_mtu and returns the maximum transfer unit.

  • Gets the size of the media (MAC-layer) address.

    Declaration

    C++

    virtual UInt8 getMediaAddressLength( void ) const;

    Return Value

    Returns the size of the media address in bytes.

    Discussion

    This method calls ifnet_addrlen and returns the media address length.

  • Gets the size of the media header.

    Declaration

    C++

    virtual UInt8 getMediaHeaderLength( void ) const;

    Return Value

    Returns the size of the media header in bytes.

    Discussion

    This method calls ifnet_hdrlen and returns the media header length.

  • Returns the BSD name prefix as a C-string.

    Declaration

    C++

    virtual const char * getNamePrefix() const = 0;

    Return Value

    Returns a pointer to a constant C-string.

    Discussion

    The BSD name for each interface object is generated by concatenating the string returned by this method, along with an unit number assigned by IONetworkStack. A concrete interface subclass must implement this method and return a distinct name prefix for its instances.

  • Gets an IONetworkData object from the interface.

    Declaration

    C++

    virtual IONetworkData * getNetworkData( const char *aKey ) const;

    Parameters

    aKey

    A C-string identifying the object.

    Return Value

    Returns a reference to the matching IONetworkData object, or NULL if no match was found.

    Discussion

    Returns a reference to an IONetworkData object that was previously added to the interface, and is associated with the provided key.

  • Gets an IONetworkData object from the interface.

    Declaration

    C++

    virtual IONetworkData * getNetworkData( const OSSymbol *aKey) const;

    Parameters

    aKey

    An OSSymbol identifying the object.

    Return Value

    Returns a reference to the matching IONetworkData object, or NULL if no match was found.

    Discussion

    Returns a reference to an IONetworkData object that was previously added to the interface, and is associated with the provided key.

  • Gets the unit number assigned to this interface object.

    Declaration

    C++

    virtual UInt16 getUnitNumber( void ) const;

    Return Value

    Returns the assigned interface unit number.

    Discussion

    This method calls ifnet_unit and returns the unit number assigned by IONetworkStack.

  • Handles a client close on the interface.

    Declaration

    C++

    virtual void handleClientClose( IOService *client, IOOptionBitsoptions );

    Parameters

    client

    The client object requesting the close.

    options

    Options same options passed to handleClose().

    Discussion

    This method is called by handleClose() to allow a subclass to handle a client close. The arbitration lock is held.

  • Handles a client open on the interface.

    Declaration

    C++

    virtual bool handleClientOpen( IOService *client, IOOptionBitsoptions, void *argument );

    Parameters

    client

    The client object requesting the open.

    options

    Options passed to handleOpen().

    argument

    Argument passed to handleOpen().

    Return Value

    Returns true to accept the client open, false to reject the open.

    Discussion

    This method is called by handleOpen() to allow a subclass to handle a client close. The arbitration lock is held.

  • Initializes the IONetworkInterface object.

    Declaration

    C++

    virtual bool init( IONetworkController *controller );

    Parameters

    controller

    A network controller object that will service the the interface.

    Return Value

    Returns true on success, false otherwise.

    Discussion

    Resources are allocated, but an ifnet_t will not be allocated until the interface is assigned a BSD name and attached to the network stack.

  • Allows a subclass to provide ifnet initialization parameters specific to an interface type.

    Declaration

    C++

    virtual bool initIfnetParams( struct ifnet_init_params *params );

    Parameters

    params

    Pointer to an ifnet_init_params allocated by the caller.

    Return Value

    Returns true on success, false otherwise.

    Discussion

    This method initializes the parameters that are common to all network interfaces. An interface subclass is expected to override this method, call the superclass implementation first, then initialize the parameters specific to that interface type. This method is called after an unit number has been assigned to the interface, and just before the interface is attached to BSD.

  • Sends an event to the network stack.

    Declaration

    C++

    virtual bool inputEvent( UInt32type, void *data );

    Parameters

    type

    A constant describing the event type.

    data

    An optional data associated with the event.

    Return Value

    Returns true if the event was delivered, false if the event type specified is invalid, or if the event delivery failed.

    Discussion

    This method can be used by the driver to send an event to the network stack.

  • For drivers to submit a received packet to the network stack.

    Declaration

    C++

    virtual UInt32 inputPacket( mbuf_t packet, UInt32 length = 0, IOOptionBits options = 0, void *param = 0 );

    Parameters

    mbuf_t

    The mbuf containing the received packet.

    length

    Specify the size of the received packet in the mbuf. The mbuf length fields are updated with this value. If zero, then the mbuf length fields are not updated.

    options

    Pass kInputOptionQueuePacket to enqueue the input packet. Pass zero to bypass the input queue, and immediately submit the packet to the network stack.

    param

    A parameter provided by the driver. Not used.

    Return Value

    Returns the number of packets that were submitted to the network stack, or zero if the packet was enqueued.

    Discussion

    The packet provided to this method may be added to an input queue managed by the interface object, which the driver can use to postpone the packet handoff to the network stack, until all received packets have been added to the input queue. A subsequent call to flushInputQueue(), will transfer the entire contents of the input queue to the network stack. This input queue is not protected by a lock. Drivers that leverage this input queue must either access the queue from a single thread, or enforce serialized access.

  • Queries whether the interface is the primary network interface on the system.

    Declaration

    C++

    virtual bool isPrimaryInterface( void ) const;

    Return Value

    Returns true if the interface is the primary interface, false otherwise.

    Discussion

    The definition of a primary interface and its discovery is platform specific.

  • Queries if the interface has attached to the BSD network stack.

    Declaration

    C++

    virtual bool isRegistered( void ) const;

    Return Value

    Returns true if interface is registered and attached to the network stack, false otherwise.

    Discussion

    Once attached a kIOBSDNameKey property is added to the interface object with the assigned BSD name.

  • Acquires a recursive lock owned by the interface.

    Declaration

    C++

    virtual void lock( void );

    Discussion

    A recursive lock is allocated and initialized in init(). This lock is otherwise not used by the IONetworkInterface class. This method call acquires the lock and must be balanced with an unlock().

  • Handles an ioctl command sent to the network interface.

    Declaration

    C++

    virtual SInt32 performCommand( IONetworkController *controller, unsigned longcmd, void *arg0, void *arg1 );

    Parameters

    controller

    The controller object.

    cmd

    The ioctl command code.

    arg0

    Command argument 0. Generally a pointer to an ifnet structure associated with the interface.

    arg1

    Command argument 1.

    Return Value

    Returns a BSD return value defined in bsd/sys/errno.h.

    Discussion

    This method handles socket ioctl commands sent to the network interface from DLIL. IONetworkInterface handles commands that are common for all network interface types. A subclass of IONetworkInterface may override this method to override the command handling in IONetworkInterface, or to extend the command processing to handle additional commands. The ioctl commands handled by IONetworkInterface are SIOCGIFMTU (Get interface MTU size), SIOCSIFMTU (Set interface MTU size), SIOCSIFMEDIA (Set media), and SIOCGIFMEDIA (Get media and link status).

  • Handles a post-change power interest notification from the network controller.

    Declaration

    C++

    virtual IOReturn powerStateDidChangeTo( IOPMPowerFlagsflags, unsigned longstateNumber, IOService *policyMaker );

    Parameters

    flags

    Flags that describe the capability of the controller in the new power state.

    stateNumber

    An index to a state in the network controller's power state array that the controller has switched to.

    policyMaker

    A reference to the network controller's policy-maker, and is also the originator of this notification.

    Return Value

    Returns IOPMAckImplied to indicate synchronous completion.

    Discussion

    The controllerDidChangePowerState() method is called by this handler. Subclasses are not expected to override this method.

  • Handles a pre-change power interest notification from the network controller.

    Declaration

    C++

    virtual IOReturn powerStateWillChangeTo( IOPMPowerFlagsflags, unsigned longstateNumber, IOService *policyMaker );

    Parameters

    flags

    Flags that describe the capability of the controller in the new power state.

    stateNumber

    An index to a state in the network controller's power state array that the controller is switching to.

    policyMaker

    A reference to the network controller's policy-maker, and is also the originator of this notification.

    Return Value

    Returns IOPMAckImplied to indicate synchronous completion.

    Discussion

    The controllerWillChangePowerState() method is called by this handler. Subclasses are not expected to override this method.

  • Registers a target/action to handle outbound packets.

    Declaration

    C++

    virtual bool registerOutputHandler( OSObject *target, IOOutputActionaction );

    Parameters

    target

    Object that implements the output handler.

    action

    The function that will handle output packets.

    Return Value

    Returns true if the target/action provided was accepted, false otherwise.

    Discussion

    The interface object will forward all output packets sent from the network stack to the target and action registered using this method. The registration must occur before the interface is registered and opened by IONetworkStack, otherwise the default handler will be used. The default target and action is set by init() as the controller, and the handler returned by the controller's getOutputHandler() method.

  • Removes an IONetworkData object from the interface.

    Declaration

    C++

    virtual bool removeNetworkData( const char *aKey );

    Parameters

    aKey

    A C-string identifying the object to be removed.

    Return Value

    Returns true if the object was found and removed, false otherwise.

    Discussion

    This method removes an IONetworkData object from the collection managed by the interface. The object removed is released.

  • Removes an IONetworkData object from the interface.

    Declaration

    C++

    virtual bool removeNetworkData( const OSSymbol *aKey );

    Parameters

    aKey

    An OSSymbol identifying the object to be removed.

    Return Value

    Returns true if the object was found and removed, false otherwise.

    Discussion

    This method removes an IONetworkData object from the collection managed by the interface. The object removed is released.

  • Performs a read-modify-write operation on the current interface flags value.

    Declaration

    C++

    virtual bool setFlags( UInt16 flags, UInt16 clear = 0 );

    Parameters

    flags

    The bits that should be set.

    clear

    The bits that should be cleared. If zero, then non of the flags are cleared and the result is formed by OR'ing the original flags value with the new flags.

    Return Value

    Always returns true.

    Discussion

    Calls ifnet_set_flags if the interface is attached to the network stack, and updates the kIOInterfaceFlags property using the provided value. See bsd/net/if.h header file for the flag constants.

  • Updates the interface object state flags.

    Declaration

    C++

    virtual UInt32 setInterfaceState( UInt32 set, UInt32 clear = 0 );

    Parameters

    set

    The flags that should be set.

    clear

    The flags that should be cleared.

    Return Value

    Returns the new interface state flags.

    Discussion

    The flags reflect the current state of the interface, and is also published through the kIOInterfaceState property.

  • Sets the interface type.

    Declaration

    C++

    virtual bool setInterfaceType( UInt8type );

    Parameters

    type

    A constant defined in bsd/net/if_types.h that describes the interface type.

    Return Value

    Returns true to indicate success if the interface has not yet attached to the network stack, otherwise returns false.

    Discussion

    Sets the interface type before the interface is attached to the network stack. See bsd/net/if_types.h for defined types. The kIOInterfaceType is also updated using the provided type.

  • Sets the maximum transfer unit for this interface.

    Declaration

    C++

    virtual bool setMaxTransferUnit( UInt32mtu );

    Parameters

    mtu

    The interface MTU size in bytes.

    Return Value

    Always returns true.

    Discussion

    Calls ifnet_set_mtu if the interface is attached to the network stack, and updates the kIOMaxTransferUnit property using the provided value.

  • Sets the size of the media (MAC-layer) address.

    Declaration

    C++

    virtual bool setMediaAddressLength( UInt8length );

    Parameters

    length

    The size of the media address in bytes.

    Return Value

    Always returns true.

    Discussion

    Calls ifnet_set_addrlen if interface is attached to the network stack, and updates the kIOMediaAddressLength property using the provided value.

  • Sets the size of the media header.

    Declaration

    C++

    virtual bool setMediaHeaderLength( UInt8length );

    Parameters

    length

    The size of the media header in bytes.

    Return Value

    Always returns true.

    Discussion

    Calls ifnet_set_hdrlen if interface is attached to the network stack, and updates the kIOMediaHeaderLength property using the provided value.

  • Assigns an unique unit number to this interface.

    Declaration

    C++

    virtual bool setUnitNumber( UInt16unit );

    Parameters

    unit

    The unit number assigned to this interface object.

    Return Value

    Returns true to indicate success if the interface has not yet attached to the network stack, otherwise returns false.

    Discussion

    This method is called internally before the interface is attached to the network stack, to assign an unique unit number to the interface object. The kIOInterfaceUnit property is also updated using the provided value.

  • Releases the recursive lock owned by the interface.

    Declaration

    C++

    virtual void unlock( void );

    Discussion

    A recursive lock is allocated and initialized in init(). This lock is otherwise not used by the IONetworkInterface class. This method call releases the lock to balance a prior lock().

Constants

  • Declaration

    CPlusPlus

    enum { kInputOptionQueuePacket = 0x1 };

    Constants

    • kInputOptionQueuePacket

      kInputOptionQueuePacket

      Enqueue the input packet provided to the input packet queue. Calls to inputPacket() must be serialized.

    Discussion

    Options for inputPacket().