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

IONetworkInterface

Inherits from:	IOService
Declared In:	IONetworkInterface.h

Overview

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

Discussion

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.

Functions

addNetworkData: Adds an IONetworkData object to a dictionary managed by the interface.
attachToDataLinkLayer: Attaches the network interface to the data link layer.
clearInputQueue: Removes and discards all packets in the input queue.
controllerDidChangePowerState: Handles a notification that the network controller servicing this interface object has transitioned to a new power state.
controllerDidOpen: Sends a notification that the interface has opened the network controller.
controllerWillChangePowerState: Handles a notification that the network controller servicing this interface object is about to transition to a new power state.
controllerWillClose: Sends a notification that the interface will close the network controller.
detachFromDataLinkLayer: Detaches the network interface from the data link layer.
feedInputPacketTap: Feed received packets to the BPF
feedOutputPacketTap: Feed sent packets to the BPF
feedPacketInputTap: Feed received packets to the BPF
feedPacketOutputTap: Feed sent packets to the BPF
flushInputQueue: Sends all packets held in the input queue to the data link layer.
free: Frees the IONetworkInterface object.
getController: Returns the provider, an IONetworkController object, that is servicing this interface object.
getExtraFlags: Gets the value of the interface extra flags.
getFlags: Gets the value of the interface flags.
getIfnet: Gets the ifnet structure allocated by the interface object.
getInterfaceState: Reports the current state of the interface object by returning the interface state flags.
getInterfaceType: Gets the interface type.
getMaxTransferUnit: Gets the maximum transfer unit for this interface.
getMediaAddressLength: Gets the size of the media (MAC-layer) address.
getMediaHeaderLength: Gets the size of the media header.
getNamePrefix: Returns a string containing the prefix to use when creating a BSD name for this interface.
getNetworkData(const char *): Gets an IONetworkData object from the interface that is associated with the given key.
getNetworkData(const OSSymbol *): Gets an IONetworkData object from the interface that is associated with the given key.
getUnitNumber: Gets the unit number assigned to this interface object.
handleClientClose: Handles a client close on the interface.
handleClientOpen: Handles a client open on the interface.
handleClose: Handles a client close on the interface.
handleIsOpen: Queries whether a client has an open on the interface.
handleOpen: Handles a client open on the interface.
init: Initializes an IONetworkInterface object.
initIfnet: Initializes the ifnet structure given.
inputEvent: Sends an event to the data link layer.
inputPacket: Submits a single packet received from the network to the data link layer.
isPrimaryInterface: Queries whether the interface object provided represents the "primary" network interface for the system.
isRegistered: Returns true if the interface has been registered with the data link layer.
lock: Takes the network interface lock.
matchPropertyTable: Overrides the implementation in IOService to implement family-specific matching.
newUserClient: Creates a connection for a non kernel client.
performCommand: Handles an ioctl command sent to the network interface.
powerStateDidChangeTo: Handles a notification that the network controller servicing this interface object has transitioned to a new power state.
powerStateWillChangeTo: Handles a notification that the network controller servicing this interface object is about to transition to a new power state.
registerOutputHandler: Registers a target/action to handle output packets.
removeNetworkData(const char *): Removes an entry from the IONetworkData dictionary managed by the interface.
removeNetworkData(const OSSymbol *): Removes an entry from the IONetworkData dictionary managed by the interface.
setExtraFlags: Performs a read-modify-write operation on the current interface extra flags value.
setFlags: Performs a read-modify-write operation on the current interface flags value.
setInterfaceState: Updates the interface object state flags.
setInterfaceType: Sest the interface type.
setMaxTransferUnit: Sets the maximum transfer unit for this interface.
setMediaAddressLength: Sets the size of the media (MAC-layer) address.
setMediaHeaderLength: Sets the size of the media header.
setProperties: Handles a request to set network interface properties from kernel or non-kernel clients.
setUnitNumber: Assigns a unique unit number to this interface.
unlock: Releases the network interface lock.

addNetworkData

Adds an IONetworkData object to a dictionary managed by the interface.

public

virtual bool addNetworkData(
    IONetworkData *aData);

Parameters

aData: An IONetworkData object to be added to a dictionary managed by the interface. This object is retained by the dictionary.

Return Value

Returns true if the operation was successful, false otherwise.

attachToDataLinkLayer

Attaches the network interface to the data link layer.

public

virtual IOReturn attachToDataLinkLayer(
    IOOptionBits options, 
    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 function is called by the family to attach the network interface managed by an IONetworkInterface to the data link layer. This call occurs after the interface initialization and setup, including the assignment of an interface unit number. Prior to the data link attach, services provided by an IONetworkInterface will be inaccessible to BSD networking, though the object can be found in the I/O Kit Registry. Subclasses can extend this function to perform additional work that is specific to a type of interface.

clearInputQueue

Removes and discards all packets in the input queue.

public

virtual UInt32 clearInputQueue();

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. Also see flushInputQueue().

controllerDidChangePowerState

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

protected

virtual IOReturn controllerDidChangePowerState( 
    IONetworkController *controller, 
    IOPMPowerFlags flags, 
    UInt32 stateNumber, 
    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.

controllerDidOpen

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

protected

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 be refused.

Discussion

This method is called by handleOpen() to notify subclasses that the controller has been opened. The open on the controller is done 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. The implementation in the subclass must first call the method in super and check the return value. This method is called with our arbitration lock held, hence issuing I/O to the controller must be avoided to eliminate the possibility of a deadlock.

controllerWillChangePowerState

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

protected

virtual IOReturn controllerWillChangePowerState( 
    IONetworkController *controller, 
    IOPMPowerFlags flags, 
    UInt32 stateNumber, 
    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.

controllerWillClose

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

protected

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 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 our arbitration lock held, hence issuing I/O to the controller must be avoided to eliminate the possibility of a deadlock.

detachFromDataLinkLayer

Detaches the network interface from the data link layer.

public

virtual void detachFromDataLinkLayer(
    IOOptionBits options, 
    void *parameter );

Parameters

options: Options for the detach call. None are currently defined.
parameter: Parameter for the detach call. Not currently used.

Discussion

This function is called by the family to detach the network interface managed by an IONetworkInterface from the data link layer. This call is made when the interface is terminated, before the last close. Subclasses can extend this function to perform additional work that is specific to a type of interface.

feedInputPacketTap

Feed received packets to the BPF

protected

virtual void feedPacketInputTap(
    mbuf_t);

Parameters

mbuf: Pointer to the packet.

Discussion

This function is called by the family for each inbound packet to feed it to the BPF function. Interface classes can override if they need to provide class specific functionality or modifications to the BPF tap.

feedOutputPacketTap

Feed sent packets to the BPF

protected

virtual void feedPacketOutputTap(
    mbuf_t);

Parameters

mbuf: Pointer to the packet.

Discussion

This function is called by the family for each outbound packet to feed it to the BPF function. Interface classes can override if they need to provide class specific functionality or modifications to the BPF tap.

feedPacketInputTap

Feed received packets to the BPF

protected

virtual void feedPacketInputTap(
    mbuf_t);

Parameters

mbuf: Pointer to the packet.

Discussion

feedPacketOutputTap

Feed sent packets to the BPF

protected

virtual void feedPacketOutputTap(
    mbuf_t);

Parameters

mbuf: Pointer to the packet.

Discussion

flushInputQueue

Sends all packets held in the input queue to the data link layer.

public

virtual UInt32 flushInputQueue();

Return Value

Returns the number of packets that were submitted to the data link layer. May be zero if the queue was empty.

Discussion

Remove all packets from the input queue and send them to the data link layer by calling dlil_input(). This method should be used in connection with the inputPacket() method, to flush the input queue after inputPacket() was used to queue up some number of received packets. See inputPacket() and clearInputQueue().

free

Frees the IONetworkInterface object.

protected

virtual void free();

Discussion

Resource allocated by init() are released, and clearInputQueue() is called to ensure that the input queue is empty.

getController

Returns the provider, an IONetworkController object, that is servicing this interface object.

public

virtual IONetworkController * getController() const;

Return Value

Returns the IONetworkController object that is providing service to this interface object.

Discussion

This is the same controller object that was supplied as an argument to the init() method.

getExtraFlags

Gets the value of the interface extra flags.

public

virtual UInt32 getExtraFlags() const;

Return Value

Returns the value of the interface extra flags.

Discussion

This method returns the value in the if_eflags field in the ifnet structure.

getFlags

Gets the value of the interface flags.

public

virtual UInt16 getFlags() const;

Return Value

Returns the value of the interface flags.

Discussion

This method returns the value in the if_flags field in the ifnet structure.

getIfnet

Gets the ifnet structure allocated by the interface object.

protected

virtual ifnet_t getIfnet() const;

Return Value

Returns the ifnet_t object that is attached to the datalink layer.

Discussion

Reveal the interface's ifnet_t. The ifnet_t is managed primarily by IONetworkInterface, however this method can be called when the sub-class needs to call interface KPI functions directly.

getInterfaceState

Reports the current state of the interface object by returning the interface state flags.

public

virtual UInt32 getInterfaceState() const;

Return Value

Returns the interface state flags.

getInterfaceType

Gets the interface type.

public

virtual UInt8 getInterfaceType() const;

Return Value

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

Discussion

This method returns the value in the if_type field in the ifnet structure.

getMaxTransferUnit

Gets the maximum transfer unit for this interface.

public

virtual UInt32 getMaxTransferUnit() const;

Return Value

Returns the interface MTU size in bytes.

Discussion

This method returns the value in the if_mtu field in the ifnet structure.

getMediaAddressLength

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

public

virtual UInt8 getMediaAddressLength() const;

Return Value

Returns the size of the media address in bytes.

Discussion

This method returns the value in the if_addrlen field in the ifnet structure.

getMediaHeaderLength

Gets the size of the media header.

public

virtual UInt8 getMediaHeaderLength() const;

Return Value

Returns the size of the media header in bytes.

Discussion

This method returns the value in the if_hdrlen field in the ifnet structure.

getNamePrefix

Returns a string containing the prefix to use when creating a BSD name for this interface.

public

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 a string returned by this method, with an unique unit number assigned by IONetworkStack. A concrete subclass of IONetworkInterface must implement this method and enforce a consistent name for all of its instances.

getNetworkData(const char *)

Gets an IONetworkData object from the interface that is associated with the given key.

public

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

Parameters

aKey: The unique string identifying the IONetworkData object to be returned to caller.

Return Value

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

getNetworkData(const OSSymbol *)

Gets an IONetworkData object from the interface that is associated with the given key.

public

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

Parameters

aKey: The unique OSSymbol identifying the IONetworkData object to be returned to caller.

Return Value

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

getUnitNumber

Gets the unit number assigned to this interface object.

public

virtual UInt16 getUnitNumber() const;

Return Value

Returns the assigned interface unit number.

Discussion

This method returns the value in the if_unit field in the ifnet structure.

handleClientClose

Handles a client close on the interface.

protected

virtual void handleClientClose(
    IOService *client, 
    IOOptionBits options);

Parameters

client: The client object requesting the close.
options: Options passed to IONetworkInterface::handleClose().

Discussion

This method is called by handleClose() to handle a close from a client object. Unlike handleClose(), subclasses may override this method to catch a close reuqest from a client. This method is called with the arbitration lock held.

handleClientOpen

Handles a client open on the interface.

protected

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

Parameters

client: The client object requesting the open.
options: Options passed to IONetworkInterface::handleOpen().
argument: Argument passed to IONetworkInterface::handleOpen().

Return Value

Returns true to accept the client open, false to refuse it.

Discussion

This method is called by handleOpen() to handle an open from a client object. Unlike handleOpen(), subclasses may override this method to catch an open request from a client. This method is called with the arbitration lock held.

handleClose

Handles a client close on the interface.

protected

virtual void handleClose(
    IOService *client,
    IOOptionBits options);

Parameters

client: The client object that requested the close.
options: Options passed to IOService::close().

Discussion

This method is called by IOService::close() with the arbitration lock held. This method will in turn call handleClientClose() to notify interested subclasses about the client close. If this represents the last close, then the interface will also close the controller before this method returns. The controllerWillClose() method will be called before closing the controller. Subclasses should not override this method.

handleIsOpen

Queries whether a client has an open on the interface.

protected

virtual bool handleIsOpen(
    const IOService * client) const;

Return Value

Returns true if the specified client, or any client if none (0) is specified, presently has an open on this object.

Discussion

This method is always called by IOService with the arbitration lock held. Subclasses should not override this method.

handleOpen

Handles a client open on the interface.

protected

virtual bool handleOpen(
    IOService *client, 
    IOOptionBits options, 
    void *argument);

Parameters

client: The client object that requested the open.
options: Options passed to IOService::open().
argument: Argument passed to IOService::open().

Return Value

Returns true to accept the client open, false otherwise.

Discussion

This method is called by IOService::open() with the arbitration lock held, and must return true to accept the client open. This method will in turn call handleClientOpen() to qualify the client requesting the open. Since the controller is opened by the interface in a lazy fashion, the interface may also perform an open on the controller before this method returns. If the controller was opened, then controllerDidOpen() is called to notify interested subclasses. Subclasses should not override this method.

init

Initializes an IONetworkInterface object.

public

virtual bool init(
    IONetworkController *controller );

Parameters

controller: A network controller object that will service the interface object being initialized.

Return Value

Returns true on success, false otherwise.

Discussion

Initializes instance variables, and allocates resources.

initIfnet

Initializes the ifnet structure given.

protected

virtual bool initIfnet(
    struct ifnet *ifp);

Parameters

ifp: Pointer to an ifnet structure obtained earlier through the getIfnet() method call.

Return Value

Returns true on success, false otherwise.

Discussion

A concrete subclass must override this method and initialize the ifnet structure given. The implementation in the subclass must call super before it returns, to allow IONetworkInterface to complete the initialization, and to insert the BSD shim functions implemented in IONetworkInterface to the appropriate function pointer fields in the ifnet structure. IONetworkInterface will call this method during its init() method. Subclasses are encouraged to use the ifnet accessor methods to update the ifnet structure when possible, since this will ensure that properties in the registry will also be updated to reflect any changes made.

inputEvent

Sends an event to the data link layer.

public

virtual bool inputEvent(
    UInt32 type,
    void *data);

Parameters

type: A constant describing the event type.
data: 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 was unsuccesful.

Discussion

This method can be used by the network controller to send an event to the data link layer.

inputPacket

Submits a single packet received from the network to the data link layer.

public

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

Parameters

m: 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: Options defined by inputPacket() that the caller can use to specify this method call.
param: A parameter provided by the caller. Not used by IONetworkInterface.

Return Value

Returns the number of packets that were submitted to the data link layer, or 0 if the packet was queued.

Discussion

This method is called by the network controller to submit a single packet received from the network to the data link layer. The packet received by this method may be added to an input queue on the interface object, which the controller can use to postpone the packet handoff to the upper layers, until all received packets have been transferred to the input queue. A subsequent call to flushInputQueue(), will transfer the entire contents of the queue to the data link layer, by making a single call to dlil_input(). Other methods that can be used to manage the input queue are flushInputQueue() and clearInputQueue(). This input queue is not protected by a lock. Access to the queue by the controller must be serialized, otherwise its use must be avoided.

isPrimaryInterface

Queries whether the interface object provided represents the "primary" network interface for the system.

public

virtual bool isPrimaryInterface() const;

Return Value

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

isRegistered

Returns true if the interface has been registered with the data link layer.

public

virtual bool isRegistered() const;

Return Value

Returns true if interface is registered. Returns false if the data link layer has no references to this network interface, which implies that either the interface has yet to attach to the data link layer, or the interface has been detached.

Discussion

Once registered, the interface will be assigned a BSD name (such as en0), and a kIOBSDNameKey property is added to the property table containing this name. Calling this method performs the same function as checking for the kIONetworkInterfaceRegisteredState bit in the value returned by getInterfaceState().

lock

Takes the network interface lock.

protected

virtual void lock();

Discussion

This method takes the recursive lock that protects the interface state. All updates to the interface state and to the ifnet structure must be performed while holding this lock. This call must be balanced by a subsequent call to unlock().

matchPropertyTable

Overrides the implementation in IOService to implement family-specific matching.

public

virtual bool matchPropertyTable(
    OSDictionary *table, 
    SInt32 *score );

Parameters

table: The dictionary of properties to match against.
score: Pointer to the current driver's probe score, not used.

Return Value

Returns true for a positive match, false otherwise.

Discussion

When the gIOLocationMatchKey property is present in the dictionary provided, then fail the match unless the kIOBSDNameKey property is found. This is to prevent a premature match when hunting for a root device for BSD. The presence of the kIOBSDNameKey property indicates that the interface has registered with BSD, and is a valid candidate for matching against the gIOLocationMatchKey property. If the gIOLocationMatchKey property is absent, then this method will always return true.

newUserClient

Creates a connection for a non kernel client.

protected

virtual IOReturn newUserClient(
    task_t owningTask, 
    void *security_id, 
    UInt32 type, 
    IOUserClient **handler);

Parameters

owningTask: The mach task requesting the connection.
security_id: A token representing the access level for the task.
type: A constant specifying the type of connection to be created. An IONetworkUserClient object is created if the type specified is kIONetworkUserClientTypeID.
handler: The IOUserClient object returned.

Return Value

Returns kIOReturnSuccess if an IONetworkUserClient was created, kIOReturnNoMemory for a memory allocation error, or kIOReturnBadArgument if the type specified is unknown.

Discussion

This method creates a new IOUserClient to service a connection to a non kernel client.

performCommand

Handles an ioctl command sent to the network interface.

protected

virtual SInt32 performCommand(
    IONetworkController *controller, 
    UInt32 cmd, 
    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, and then call super for any commands not handled in the subclass. 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).

powerStateDidChangeTo

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

protected

virtual IOReturn powerStateDidChangeTo(
    IOPMPowerFlags flags, 
    UInt32 stateNumber, 
    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

The return will always be IOPMAckImplied to indicate that the preparation for the power change has already completed when this method returns.

Discussion

This method will call the controllerDidChangePowerState() method on the controller's work loop context to prepare for the power state change. Subclasses should not override this method.

powerStateWillChangeTo

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

protected

virtual IOReturn powerStateWillChangeTo(
    IOPMPowerFlags flags, 
    UInt32 stateNumber, 
    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

The return will always be IOPMAckImplied to indicate that the preparation for the power change has already completed when this method returns.

Discussion

This method will call the controllerWillChangePowerState() method on the controller's work loop context to prepare for the power state change. Subclasses should not override this method.

registerOutputHandler

Registers a target/action to handle output packets.

public

virtual bool registerOutputHandler(
    OSObject *target, 
    IOOutputAction action);

Parameters

target: Target object that implements the output handler.
action: The function that will process output packets.

Return Value

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

Discussion

The interface object will forward all output packets, received from the data link layer, to the output handler registered through this method. The default target and action are set by the init() method to the controller, and the handler returned by the controller's getOutputHandler() method. Once the interface becomes registered with the data link layer, this method will return false and will reject any further changes.

removeNetworkData(const char *)

Removes an entry from the IONetworkData dictionary managed by the interface.

public

virtual bool removeNetworkData(
    const char * aKey);

Parameters

aKey: A unique string identifying the IONetworkData object to be removed from the dictionary.

Return Value

Returns true if the operation was successful, false otherwise.

Discussion

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

removeNetworkData(const OSSymbol *)

Removes an entry from the IONetworkData dictionary managed by the interface.

public

virtual bool removeNetworkData(
    const OSSymbol * aKey);

Parameters

aKey: A unique OSSymbol identifying the IONetworkData object to be removed from the dictionary.

Return Value

Returns true if the operation was successful, false otherwise.

Discussion

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

setExtraFlags

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

protected

virtual bool setExtraFlags(
    UInt32 flags,
    UInt32 clear = 0);

Parameters

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

Return Value

Returns true if the update was successful, false otherwise.

Discussion

See bsd/net/if.h header file for the definition of the extra flag constants. Both the if_eflags field in the ifnet structure, and the kIOInterfaceExtraFlags property are updated with the value provided.

setFlags

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

protected

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

Parameters

flags: The bits that should be set.
clear: The bits that should be cleared. If 0, 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

Returns true if the update was successful, false otherwise.

Discussion

See bsd/net/if.h header file for the definition of the flag constants. Both the if_flags field in the ifnet structure, and the kIOInterfaceFlags property are updated with the value provided.

setInterfaceState

Updates the interface object state flags.

protected

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

Parameters

flags: The bits that should be set.
clear: The bits that should be cleared.

Return Value

Returns the resulting interface state flags following any changes made by this method.

Discussion

The kIOInterfaceState property is updated with the value provided.

setInterfaceType

Sest the interface type.

protected

virtual bool setInterfaceType(
    UInt8 type);

Parameters

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

Return Value

Returns true if the update was successful, false otherwise.

Discussion

Both the if_type field in the ifnet structure, and the kIOInterfaceType property are updated with the value provided.

setMaxTransferUnit

Sets the maximum transfer unit for this interface.

protected

virtual bool setMaxTransferUnit(
    UInt32 mtu);

Parameters

mtu: The interface MTU size in bytes.

Return Value

Returns true if the update was successful, false otherwise.

Discussion

Both the if_mtu field in the ifnet structure, and the kIOMaxTransferUnit property are updated with the value provided.

setMediaAddressLength

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

protected

virtual bool setMediaAddressLength(
    UInt8 length);

Parameters

length: The size of the media address in bytes.

Return Value

Returns true if the update was successful, false otherwise.

Discussion

Both the if_addrlen field in the ifnet structure, and the kIOMediaAddressLength property are updated with the value provided.

setMediaHeaderLength

Sets the size of the media header.

protected

virtual bool setMediaHeaderLength(
    UInt8 length);

Parameters

length: The size of the media header in bytes.

Return Value

Returns true if the update was successful, false otherwise.

Discussion

Both the if_hdrlen field in the ifnet structure, and the kIOMediaHeaderLength property are updated with the value provided.

setProperties

Handles a request to set network interface properties from kernel or non-kernel clients.

public

virtual IOReturn setProperties(
    OSObject *properties );

Parameters

properties: An OSDictionary containing a collection of properties.

Return Value

Returns kIOReturnUnsupported if the interface did not recognize any of the properties provided. Otherwise, the return code will be kIOReturnSuccess to indicate no errors, or an IOReturn error code to indicate that an error occurred while handling one of the properties.

Discussion

For non-kernel clients, the preferred access mechanism is through a user client connection.

setUnitNumber

Assigns a unique unit number to this interface.

protected

virtual bool setUnitNumber(
    UInt16 unit);

Parameters

unit: The unit number assigned to this interface object.

Return Value

Returns true if the update was successful, false otherwise.

Discussion

This method is called by IONetworkStack before the interface is registered with the data link layer, to assign a unique unit number to the interface object. Both the if_unit field in the ifnet structure, and the kIOInterfaceUnit property are updated with the value provided.

unlock

Releases the network interface lock.

protected

virtual void unlock();

Discussion

This method releases the recursive lock that protects the interface state to balance a previous lock() call.

Member Data

_reserved

See Also:

reserved

private

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

reserved

See Also:

_reserved

private

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

Enumerations

InputOptionQueuePacket

public

enum { 
    kInputOptionQueuePacket = 0x1 
};

Constants

kInputOptionQueuePacket

Keep the packet provided in the input packet queue. No packets are sent to the data link layers, and the caller's thread will not venture outside the interface object. Calls to inputPacket() must be serialized.

Discussion

The option bits that can be specified in the options argument when calling inputPacket().

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