IONetworkInterface



Member Functions

attachToParent

protected:

virtual bool attachToParent(IORegistryEntry * parent, const IORegistryPlane * plane);

Called by IOService::attach() when the interface is attached to a controller. This method checks that the parent object that the interface is attached to is a type of IONetworkController.

Parameters

NameDescription
parentThe registry entry to attach to.
planeThe plane object.
Result: true on success, false otherwise.

clearInputQueue

public:

virtual UInt32 clearInputQueue();

Remove all packets in the interface's input queue and release them back to the free buffer pool. The packets are not submitted to the network layer. Also see flushInputQueue().

Result: The number of packets released.

controllerDidOpen

protected:

virtual bool controllerDidOpen(IONetworkController * controller);

Called by handleOpen() to configure the controller after it has just been opened. The open on the controller occurs after the interface receives the initial open request from a client. Subclasses can override this method and setup the controller before allowing the client open. The implementation in the subclass must call the method in super and check the return value.

Parameters

NameDescription
controllerThe controller that was opened.
Result: This method 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 rejected.

controllerWillClose

protected:

virtual void controllerWillClose(IONetworkController * controller);

Called by handleClose() after receiving a close from the last client, and before the controller is closed. Subclasses can override this method to perform any cleanup action before the controller is closed.

Parameters

NameDescription
controllerThe controller that will be closed.

feedInputFilterTap

public:

virtual void feedInputFilterTap(struct mbuf * pkt);

Feed a packet to the input filter tap. This method should not be called if the input filter tap mode is set to kIOFilterTapModeInternal, since the tap would automatically receive every input packet that flows through the interface. A call to feedInputFilterTap() under this condition would cause the tap to incorrectly receive the same packet twice.

Parameters

NameDescription
pktThe packet mbuf to pass to the input tap. The rcvif field in the mbuf is modified by this method.

feedOutputFilterTap

public:

virtual void feedOutputFilterTap(struct mbuf * pkt);

Feed a packet to the output filter tap. This method should not be called if the output filter tap mode is set to kIOFilterTapModeInternal, since the tap would automatically receive every output packet that flows through the interface. A call to feedOutputFilterTap() under this condition would cause the tap to incorrectly receive the same packet twice.

Parameters

NameDescription
pktThe packet mbuf to pass to the output tap.

flushInputQueue

public:

virtual UInt32 flushInputQueue();

Remove all packets in the interface's input queue and submit them to the network layer by calling dlil_input(). This method should be used in connection with the inputPacket() method, in order to flush the input queue after inputPacket() has queued all received packets. Also see inputPacket() and clearInputQueue().

Result: The number of packets submitted to the network layer. May be zero if the queue is empty.

free

protected:

virtual void free();

Free the IONetworkInterface instance and release allocated resources.


getExtraFlags

public:

virtual UInt32 getExtraFlags() const;

Result: The if_eflags field in the ifnet structure associated with the interface.

getFlags

public:

virtual UInt16 getFlags() const;

Result: The if_flags field in the ifnet structure associated with the interface.

getIfnet

protected:

virtual struct ifnet * getIfnet() const = 0;

Request an interface to reveal its ifnet structure. A concrete subclass must allocate an ifnet structure when the object is initialized, and return a pointer to the ifnet structure when this method is called.

Result: Pointer to an ifnet structure allocated by a concrete subclass.

getInputFilterTapMode

public:

virtual IOFilterTapMode getInputFilterTapMode() const;

Result: Returns the current mode of the input packet tap.

getInterfaceName

public:

virtual const char * getInterfaceName() const;

Result: The if_name field in the ifnet structure associated with the interface.

getInterfaceState

public:

virtual UInt32 getInterfaceState() const;

Result: Returns the current state of the interface.

getInterfaceType

public:

virtual UInt8 getInterfaceType() const;

Result: The assigned interface type that matches one of the types defined in bsd/net/if_types.h.

getMaxTransferUnit

public:

virtual UInt32 getMaxTransferUnit() const;

Result: The interface MTU size.

getMediaAddressLength

public:

virtual UInt8 getMediaAddressLength() const;

Result: The if_data.ifi_addrlen field in the ifnet structure associated with the interface.

getMediaHeaderLength

public:

virtual UInt8 getMediaHeaderLength() const;

Result: The if_data.ifi_hdrlen field in the ifnet structure associated with the interface.

getNamePrefix

public:

virtual const char * getNamePrefix() const = 0;

The name of the interface advertised to the network layer is generated by concatenating the string returned by this method, and an integer unit number assigned by an external entity. This method must be implemented by a family specific subclass.

Result: A pointer to a constant string.

getOutputFilterTapMode

public:

virtual IOFilterTapMode getOutputFilterTapMode() const;

Result: Returns the current mode of the input packet tap.

getParameter

public:

virtual IONetworkParameter * getParameter(const OSSymbol * key) const;

Search of the parameter dictionary populated through publishParameters(), and return an entry that matches the specified OSSymbol key.

Parameters

NameDescription
keySearch for an entry with this OSSymbol key.
Result: The matching entry, or 0 if no match was found.

getParameter

public:

virtual IONetworkParameter * getParameter(const char * key) const;

Perform a lookup of the parameter dictionary populated through publishParameters(), and return the entry that matches the specified string key.

Parameters

NameDescription
keySearch for an entry with this string key.
Result: The matching entry, or 0 if no match was found.

getUnitNumber

public:

virtual UInt16 getUnitNumber() const;

Result: The assigned interface unit number.

handleClientClose

protected:

virtual void handleClientClose(IONetworkController * controller, IOService * client);

Called by handleOpen() to notify that a client object has closed the interface.

Parameters

NameDescription
controllerThe controller object (provider).
clientThe client object.

handleClientOpen

protected:

virtual bool handleClientOpen(IONetworkController * controller, IOService * client);

Called by handleOpen() to qualify a client object that is attempting to open the interface.

Parameters

NameDescription
controllerThe controller object (provider).
clientThe client object.
Result: true to accept the client open, false to refuse the open.

handleClose

protected:

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

Handle a close by one of our clients. The close() method in IOService calls this method with the arbitration lock held. This method will in turn call handleClientClose() and controllerWillClose(). Subclasses must not override this method.

Parameters

NameDescription
clientThe client object that requested the close.
optionsNot used. See IOService.

handleIsOpen

protected:

virtual bool handleIsOpen(const IOService * client) const;

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

Result: true if the specified client, or any client if none is specified, presently has an open on this object.

handleOpen

protected:

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

Handle a client open on this object. The open() method in IOService calls this method with the arbitration lock held, and this method must return true to accept the client open. This method will in turn call handleClientOpen() and controllerDidOpen(). Subclasses must not override this method.

Parameters

NameDescription
clientThe client object that requested the open.
optionsNot used. See IOService.
argumentNot used. See IOService.
Result: true to accept the client open, false otherwise.

init

public:

virtual bool init(OSDictionary * properties = 0);

Initialize an IONetworkInterface instance.

Parameters

NameDescription
propertiesA property dictionary.
Result: true if initialized successfully, false otherwise.

initIfnet

protected:

virtual bool initIfnet(struct ifnet * ifp);

Initialize the ifnet structure. Subclasses must override this method and initialize the ifnet structure given in a family specific manner. Subclasses may use the "setter" methods such as setFlags() to initialize the ifnet fields. The implementation in the subclass must call the version in super before it returns, and allow IONetworkInterface to complete the initialization.

Parameters

NameDescription
ifpPointer to an ifnet structure obtained earlier through the getIfnet() call.
Result: true on success, false otherwise.

inputEvent

public:

virtual void inputEvent(UInt32 eventType, void * arg);

Called by the controller driver to send a defined event to the network layer. Possible applications include: media changed events, power management events, controller state change events.

Parameters

NameDescription
eventTypeThe event type.
argAn argument associated with the event type.

inputPacket

public:

virtual UInt32 inputPacket(struct mbuf * m, UInt32 length = 0, bool queuePkt = false);

Called by the controller to pass a received packet to the network layer. If the length specified is not zero, then the packet will be truncated to the given length. Packets received by this method can also be placed on a queue local to the interface, that the controller can use to delay the packet handoff to the network layer until all received packets have been transferred to the queue. A flushInputQueue(), or a inputPacket() call with 'queuePkt' argument set to false will cause any queued packets (may be a single packet) to be submitted to the network layer, by calling dlil_input() (defined by DLIL) only once. Additional methods that manipulates the input queue are flushInputQueue() and clearInputQueue(). The input queue is not protected by a lock since the controller is expected to call all methods that touches the queue from a single thread.

Parameters

NameDescription
mThe packet mbuf containing the received frame.
lengthIf non zero, the mbuf given will be truncated to the length given. If zero, then no truncation will take place.
queuePktIf true, the only action performed is to queue the input packet. Otherwise, the dlil_input() function is also called to submit any queued packets.
Result: The number of packets submitted to the network layer.

issueRequest

public:

virtual IOReturn issueRequest(OSObject * sender, UInt32 request, void * arg0 = 0, void * arg1 = 0, void * arg2 = 0, void * arg3 = 0);

Issue a request to the network controller by calling its requestHandler() method.

Parameters

NameDescription
senderThis sender of the request, usually set to 'this'.
requestThe request type.
arg0Request argument.
arg1Request argument.
arg2Request argument.
arg3Request argument.
Result: kIOReturnSuccess if the request was issued and handled successfully.

issueRequest

public:

virtual IOReturn issueRequest(UInt32 request, void * arg0 = 0, void * arg1 = 0, void * arg2 = 0, void * arg3 = 0);

Issue a request to the network controller by calling its requestHandler() method. The sender of the request is set to 'this'.

Parameters

NameDescription
requestThe request type.
arg0Request argument.
arg1Request argument.
arg2Request argument.
arg3Request argument.
Result: kIOReturnSuccess if the request was issued and handled successfully.

lock

protected:

virtual void lock();

Take the recursive lock that protects the interface data and state.


newUserClient

protected:

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

Create a new IOUserClient to handle userspace client requests. The default implementation will create an IONetworkUserClient instance if the type given is kIONUCType.

Parameters

NameDescription
owningTaskSee IOService.
security_idSee IOService.
typeSee IOService.
handlerSee IOService.
Result: kIOReturnSuccess if an IONetworkUserClient was created.

performCommand

protected:

virtual SInt performCommand(IONetworkController * controller, UInt32 cmd, void * arg0, void * arg1);

Handles generic socket ioctl commands. IONetworkInterface handles commands that are common to all network families. A family specific subclass of IONetworkInterface may override this function in order to handle commands specific to its family. Any commands not handled in the subclass should be forwarded to its superclass. 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).

Parameters

NameDescription
controllerThe controller object.
cmdThe command code.
arg0Command argument.
arg1Command argument.
Result: A BSD error code defined in bsd/sys/errno.h.

publishParameters

public:

virtual void publishParameters(OSDictionary * array) const;

A dictionary is created to store IONetworkParameter objects created by IONetworkInterface and also by its subclasses. This method is called to collect those parameters, by passing the dictionary object, and allowing the receiver to add its parameter objects to the dictionary. Subclasses can override this method, but it must also call the method in super.

Parameters

NameDescription
dictThe dictionary that the receiver may use to add its IONetworkParameter objects.

registerOutputHandler

public:

virtual bool registerOutputHandler(const IOOutputHandler * handler);

Register the output handler.

Parameters

NameDescription
handlerPointer to an IOOutputHandler structure provided by the caller.
Result: true if the handler provided was accepted, false otherwise.

setExtraFlags

public:

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

Perform a read-modify-write operation on the if_eflags field in the ifnet structure associated with the interface.

Parameters

NameDescription
flagsThe flags that should be set.
clearThe flags that should be cleared. If this value is 0, then no flags are cleared and the result is formed by OR'ing the original flags with the new flags.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setExtraFlagsInt

protected:

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

Perform a read-modify-write operation on the if_eflags field in the ifnet structure associated with the interface.

Parameters

NameDescription
flagsThe flags that should be set.
clearThe flags that should be cleared. If this value is 0, then no flags are cleared and the result is formed by OR'ing the original flags with the new flags.
Result: true if the update was successful, false otherwise.

setFlags

public:

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

Performs a read-modify-write operation on the if_flags field in the ifnet structure associated with the interface.

Parameters

NameDescription
flagsThe flags that should be set.
clearThe flags that should be cleared. If this value is 0, then no flags are cleared and the result is formed by OR'ing the original flags with the new flags.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setFlagsInt

protected:

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

Performs a read-modify-write operation on the if_flags field in the ifnet structure associated with the interface.

Parameters

NameDescription
flagsThe flags that should be set.
clearThe flags that should be cleared. If this value is 0, then no flags are cleared and the result is formed by OR'ing the original flags with the new flags.
Result: true if the update was successful, false otherwise.

setInputFilterTapMode

public:

virtual bool setInputFilterTapMode(IOFilterTapMode mode);

Set the mode of the input packet tap, to specify how the tap will connect to the input packet flow once the tap becomes enabled. See IOFilterTapMode enumeration.

Parameters

NameDescription
Thenew mode.
Result: true if the new mode was accepted, false otherwise.

setInterfaceName

public:

virtual bool setInterfaceName(const char * name);

Parameters

NameDescription
nameThe new value for the if_name field in the ifnet structure associated with the interface.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setInterfaceNameInt

protected:

virtual bool setInterfaceNameInt(const char * name);

Parameters

NameDescription
nameThe new value for the if_name field in the ifnet structure associated with the interface.
Result: true if the update was successful, false otherwise.

setInterfaceType

public:

virtual bool setInterfaceType(UInt8 type);

Parameters

NameDescription
typeThe type of the interface. See bsd/net/if_types.h for the defined types.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setInterfaceTypeInt

protected:

virtual bool setInterfaceTypeInt(UInt8 type);

Parameters

NameDescription
typeThe type of the interface. See bsd/net/if_types.h for defined types.
Result: true if the update was successful, false otherwise.

setMaxTransferUnit

public:

virtual bool setMaxTransferUnit(UInt32 mtu);

Parameters

NameDescription
mtuThe new interface MTU size.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setMaxTransferUnitInt

protected:

virtual bool setMaxTransferUnitInt(UInt32 mtu);

Parameters

NameDescription
mtuThe new interface MTU size.
Result: true if the update was successful, false otherwise.

setMediaAddressLength

public:

virtual bool setMediaAddressLength(UInt8 length);

Parameters

NameDescription
lengthThe new value for the if_data.ifi_addrlen field in the ifnet structure associated with the interface.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setMediaAddressLengthInt

protected:

virtual bool setMediaAddressLengthInt(UInt8 length);

Parameters

NameDescription
lengthThe new value for the if_data.ifi_addrlen field in the ifnet structure associated with the interface.
Result: true if the field was updated, false otherwise.

setMediaHeaderLength

public:

virtual bool setMediaHeaderLength(UInt8 length);

Parameters

NameDescription
lengthThe new value for the if_data.ifi_hdrlen field in the ifnet structure associated with the interface.
Result: true if the current state is kStateUnregistered and the update was successful, false otherwise.

setMediaHeaderLengthInt

protected:

virtual bool setMediaHeaderLengthInt(UInt8 length);

Parameters

NameDescription
lengthThe new value for the if_data.ifi_hdrlen field in the ifnet structure associated with the interface.
Result: true if the update was successful, false otherwise.

setOutputFilterTapMode

public:

virtual bool setOutputFilterTapMode(IOFilterTapMode mode);

Set the mode of the output packet tap, to specify how the tap will connect to the output packet flow once the tap becomes enabled. See IOFilterTapMode enumeration.

Parameters

NameDescription
Thenew mode.
Result: true if the new mode was accepted, false otherwise.

setUnitNumber

public:

virtual bool setUnitNumber(UInt16 unit);

Parameters

NameDescription
unitThe unit number to assign to this interface.
Result: true if the current state is kStateUnregistered and the unit number was accepted, false otherwise.

setUnitNumberInt

protected:

virtual bool setUnitNumberInt(UInt16 unit);

Parameters

NameDescription
unitThe unit number to assign to this interface.
Result: true if the unit number was accepted, false otherwise.

unlock

protected:

virtual void unlock();

Release the recursive lock that protects the interface data and state.


Member Data

State

public:
  enum  {
  kStateUnregistered,
  kStateRegistered
  };

The state of the interface returned by getInterfaceState().

Constants

NameDescription
kStateUnregisteredThe interface has no client (IOUserClient excluded), hence the interface is not registered with the network layer.
kStateRegisteredA client has opened the interface, and the interface is registered with the network layer.

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)