|
ADC Home > Reference Library > Reference > Darwin > KPI Reference
|
kpi_interface.h |
| Includes: | <sys/kernel_types.h> |
This header defines an API to interact with network interfaces in the kernel. The network interface KPI may be used to implement network interfaces or to attach protocols to existing interfaces.
ifaddr_address(ifaddr_t) |
sa_family_t ifaddr_address_family( ifaddr_t ifaddr);
ifaddr0 on failure, address family on success.
Returns the address family of the address.
ifaddr_address(ifaddr_t, struct sockaddr *, u_int32_t) |
errno_t ifaddr_address( ifaddr_t ifaddr, struct sockaddr *out_addr, u_int32_t addr_size);
ifaddrout_addraddr_size0 upon success
Copies the address out of the ifaddr.
ifaddr_address_family |
sa_family_t ifaddr_address_family( ifaddr_t ifaddr);
ifaddr0 on failure, address family on success.
Returns the address family of the address.
ifaddr_dstaddress |
errno_t ifaddr_dstaddress( ifaddr_t ifaddr, struct sockaddr *out_dstaddr, u_int32_t dstaddr_size);
ifaddrout_dstaddrdstaddr_size0 upon success
Copies the destination address out of the ifaddr.
ifaddr_findbestforaddr |
ifaddr_t ifaddr_findbestforaddr( const struct sockaddr *addr, ifnet_t interface);
addrinterfaceA reference to the interface address.
Finds the best local address assigned to a specific interface to use when communicating with another address. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.
ifaddr_ifnet |
ifnet_t ifaddr_ifnet( ifaddr_t ifaddr);
ifaddrA reference to the interface the address is attached to.
Returns the interface the address is attached to. The reference is only valid until the ifaddr is released. If you need to hold a reference to the ifnet for longer than you hold a reference to the ifaddr, increment the reference using ifnet_reference.
ifaddr_netmask |
errno_t ifaddr_netmask( ifaddr_t ifaddr, struct sockaddr *out_netmask, u_int32_t netmask_size);
ifaddrout_netmasknetmask_size0 upon success
Copies the netmask out of the ifaddr.
ifaddr_reference |
errno_t ifaddr_reference( ifaddr_t ifaddr);
ifaddr0 upon success
Increment the reference count of an address tied to an interface.
ifaddr_release |
errno_t ifaddr_release( ifaddr_t ifaddr);
ifaddr0 upon success
Decrements the reference count of and possibly frees an address tied to an interface.
ifaddr_withaddr |
ifaddr_t ifaddr_withaddr( const struct sockaddr*address);
addressA reference to the interface address.
Returns an interface address with the address specified. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.
ifaddr_withdstaddr |
ifaddr_t ifaddr_withdstaddr( const struct sockaddr*destination);
destinationA reference to the interface address.
Returns an interface address for the interface address that matches the destination when the netmask is applied. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.
ifaddr_withnet |
ifaddr_t ifaddr_withnet( const struct sockaddr*net);
netA reference to the interface address.
Returns an interface address for the interface with the network described by net. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.
ifaddr_withroute |
ifaddr_t ifaddr_withroute( int flags, const struct sockaddr*destination, const struct sockaddr*gateway);
flagsdestinationgatewayA reference to the interface address.
Returns an interface address given a destination and gateway. Increments the reference count on the ifaddr before returning to the caller. Caller is responsible for calling ifaddr_release.
ifmaddr_address |
errno_t ifmaddr_address( ifmultiaddr_t ifmaddr, struct sockaddr *out_multicast, u_int32_t addr_size);
out_multicastaddr_size0 on success.
Copies the multicast address to out_multicast.
ifmaddr_ifnet |
ifnet_t ifmaddr_ifnet( ifmultiaddr_t ifmaddr);
ifmaddrA reference to the interface.
Returns the interface this multicast address is attached to. The interface reference count is not bumped by this function. The interface is only valid as long as you don't release the refernece to the multiast address. If you need to maintain your pointer to the ifnet, call ifnet_reference followed by ifnet_release when you're finished.
ifmaddr_lladdress |
errno_t ifmaddr_lladdress( ifmultiaddr_t ifmaddr, struct sockaddr *out_link_layer_multicast, u_int32_t addr_size);
out_link_layer_multicastaddr_size0 on success.
Copies the link layer multicast address to out_link_layer_multicast.
ifmaddr_reference |
errno_t ifmaddr_reference( ifmultiaddr_t ifmaddr);
ifmaddr0 on success. Only error will be EINVAL if ifmaddr is not valid.
Increment the reference count of an interface multicast address.
ifmaddr_release |
errno_t ifmaddr_release( ifmultiaddr_t ifmaddr);
ifmaddr0 on success. Only error will be EINVAL if ifmaddr is not valid.
Decrement the reference count of an interface multicast address. If the reference count reaches zero, the ifmultiaddr will be removed from the interface and the ifmultiaddr will be freed.
ifnet_add_multicast |
errno_t ifnet_add_multicast( ifnet_t interface, const struct sockaddr *maddr, ifmultiaddr_t *multicast);
interfacemaddrmulticast0 on success otherwise the errno error.
Joins a multicast and returns an ifmultiaddr_t with the reference count incremented for you. You are responsible for decrementing the reference count after calling ifnet_remove_multicast and making sure you no longer have any references to the multicast.
ifnet_addrlen |
u_int8_t ifnet_addrlen( ifnet_t interface);
interfaceThe address length.
ifnet_allocate |
errno_t ifnet_allocate( const struct ifnet_init_params *init, ifnet_t *interface);
initinterfaceMay return ENOMEM if there is insufficient memory or EEXIST if an interface with the same uniqueid and family has already been allocated and is in use.
Allocate an ifnet_t with an initial refcount of 1. Many parts of the stack do not properly refcount the ifnet_t. In order to avoid freeing the ifnet_t while some parts of the stack may contain a reference to it, the ifnet_ts are only recycled, never freed. A unique id is used to try and recycle the same ifnet_t when allocating an interface. For example, for an ethernet interface, the hardware address of the ethernet card is usually used for the uniqueid. If a PC Card is removed and inserted again, if the ethernet address of the PC card is used, the same ifnet_t will be used for the card the second time it is inserted. In the future, when the ifnet_t is correctly refcounted by all of the stack, the interfaces may be freed and the unique ids ignored.
ifnet_attach |
errno_t ifnet_attach( ifnet_t interface, const struct sockaddr_dl *ll_addr);
interfacell_addrWill return an error if there is anything wrong with the interface.
Attaches an interface to the global interface list. The
interface must be setup properly before calling attach. The
stack will take a reference on the interface and hold it until
ifnet_detach is called.
This function is intended to be called by the driver. A kext
must not call this function on an interface the kext does not
own.
ifnet_attach_protocol |
errno_t ifnet_attach_protocol( ifnet_t interface, protocol_family_t protocol_family, const struct ifnet_attach_proto_param *proto_details);
interfaceprotocol_familyproto_details0 on success otherwise the errno error.
Attaches a protocol to an interface.
ifnet_baudrate |
u_int64_t ifnet_baudrate( ifnet_t interface);
interfaceThe baudrate.
ifnet_detach |
errno_t ifnet_detach( ifnet_t interface);
interface0 on success, otherwise errno error.
Detaches the interface.
Call this to indicate this interface is no longer valid (i.e. PC
Card was removed). This function will begin the process of
removing knowledge of this interface from the stack.
The function will return before the interface is detached. The
functions you supplied in to the interface may continue to be
called. When the detach has been completed, your detached
function will be called. Your kext must not unload until the
detached function has been called. The interface will be
properly freed when the reference count reaches zero.
An interface may not be attached again. You must call
ifnet_allocate to create a new interface to attach.
This function is intended to be called by the driver. A kext
must not call this function on an interface the kext does not
own.
ifnet_detach_protocol |
errno_t ifnet_detach_protocol( ifnet_t interface, protocol_family_t protocol_family);
interfaceprotocol_family0 on success otherwise the errno error.
Detaches a protocol from an interface.
ifnet_event |
errno_t ifnet_event( ifnet_t interface, struct kern_event_msg*event_ptr);
interfaceevent_ptr0 on success otherwise the errno error.
Calls the interface's event function.
ifnet_family |
ifnet_family_t ifnet_family( ifnet_t interface);
interfaceUnit number.
Returns the family of the interface.
ifnet_find_by_name |
errno_t ifnet_find_by_name( const char *ifname, ifnet_t *interface);
nameinterface0 on success otherwise the errno error.
Find an interface by the name including the unit number. Caller must call ifnet_release on any non-null interface return value.
ifnet_flags |
u_int16_t ifnet_flags( ifnet_t interface);
interfaceFlags. These flags are defined in net/if.h
Returns the interface flags that are set.
ifnet_free_address_list |
void ifnet_free_address_list( ifaddr_t *addresses);
addressesFree a list of addresses returned from ifnet_get_address_list. Decrements the refcounts and frees the memory used for the array of references.
ifnet_free_multicast_list |
void ifnet_free_multicast_list( ifmultiaddr_t *multicasts);
multicasts0 on success otherwise the errno error.
Frees a list of multicasts returned by ifnet_get_multicast_list. Decrements the refcount on each multicast address and frees the array.
ifnet_get_address_list |
errno_t ifnet_get_address_list( ifnet_t interface, ifaddr_t **addresses);
interfaceaddresses0 on success otherwise the errno error.
Get a list of addresses on the interface. Passing NULL
for the interface will return a list of all addresses. The
addresses will have their reference count bumped so they will
not go away. Calling ifnet_free_address_list will decrement the
refcount and free the array. If you wish to hold on to a
reference to an ifaddr_t, be sure to bump the reference count
before calling ifnet_free_address_list.
Old versions of this function erroneously returned EINVAL when
passed NULL for the interface. Passing NULL will not work on
some versions of MacOS X 10.4.
ifnet_get_address_list_family |
errno_t ifnet_get_address_list_family( ifnet_t interface, ifaddr_t **addresses, sa_family_t family);
interfaceaddresses0 on success otherwise the errno error.
Get a list of addresses on the interface. Passing NULL for the interface will return a list of all addresses. The addresses will have their reference count bumped so they will not go away. Calling ifnet_free_address_list will decrement the refcount and free the array. If you wish to hold on to a reference to an ifaddr_t, be sure to bump the reference count before calling ifnet_free_address_list. Unlike ifnet_get_address_list, this function lets the caller specify the address family to get a list of only a specific address type. Old versions of this function erroneously returned EINVAL when passed NULL for the interface. Passing NULL will not work on some versions of MacOS X 10.4.
ifnet_get_link_mib_data |
errno_t ifnet_get_link_mib_data( ifnet_t interface, void *mibData, u_int32_t *mibLen);
interfacemibDatamibLenReturns an error if the buffer size is too small or there is no data.
Copies the link MIB data in to mibData, up to mibLen bytes. Returns error if the buffer is too small to hold all of the MIB data.
ifnet_get_link_mib_data_length |
u_int32_t ifnet_get_link_mib_data_length( ifnet_t interface);
interfaceReturns the number of bytes of mib data associated with the interface.
Retrieve the size of the mib data.
ifnet_get_multicast_list |
errno_t ifnet_get_multicast_list( ifnet_t interface, ifmultiaddr_t **addresses);
interfacemulticasts0 on success otherwise the errno error.
Retrieves a list of multicast address the interface is set to receive. This function allocates and returns an array of references to the various multicast addresses. The multicasts have their reference counts bumped on your behalf. Calling ifnet_free_multicast_list will decrement the reference counts and free the array.
ifnet_hdrlen |
u_int8_t ifnet_hdrlen( ifnet_t interface);
interfaceThe header length.
ifnet_index |
u_int32_t ifnet_index( ifnet_t interface);
interfaceIndex.
Returns the index of the interface. This index value will match the index you would find in a sockaddr_dl or using if_nametoindex or if_indextoname in user space. The value of the interface index is undefined for an interface that is not currently attached.
ifnet_input |
errno_t ifnet_input( ifnet_t interface, mbuf_t first_packet, const struct ifnet_stat_increment_param *stats);
interfacefirst_packetstats0 on success otherwise the errno error.
Inputs packets from the interface. The interface's demux will be called to determine the protocol. Once the protocol is determined, the interface filters and protocol filters will be called. From there, the packet will be passed to the registered protocol. If there is an error, the mbuf chain will be freed.
ifnet_ioctl |
errno_t ifnet_ioctl( ifnet_t interface, protocol_family_t protocol, u_int32_t ioctl_code, void *ioctl_arg);
interfaceprotocolioctl_codeioctl_arg0 on success otherwise the errno error.
Calls the interface's ioctl function with the parameters
passed.
All undefined ioctls are reserved for future use by Apple. If
you need to communicate with your kext using an ioctl, please
use SIOCSIFKPI and SIOCGIFKPI.
ifnet_lastchange |
errno_t ifnet_lastchange( ifnet_t interface, struct timeval *last_change);
interfacelast_changeifnet_list_free |
void ifnet_list_free( ifnet_t *interfaces);
interfacesFree a list of interfaces returned by ifnet_list_get. Decrements the reference count on each interface and frees the array of references. If you keep a reference to an interface, be sure to increment the reference count before calling ifnet_list_free.
ifnet_list_get |
errno_t ifnet_list_get( ifnet_family_t family, ifnet_t **interfaces, u_int32_t *count);
familyinterfacescount0 on success otherwise the errno error.
Get a list of attached interfaces. List will be set to point to an array allocated by ifnet_list_get. The interfaces are refcounted and the counts will be incremented before the function returns. The list of interfaces must be freed using ifnet_list_free.
ifnet_lladdr_copy_bytes |
errno_t ifnet_lladdr_copy_bytes( ifnet_t interface, void*lladdr, size_t length);
interfacelladdrlengthCopies the bytes of the link-layer address in to the specified buffer.
ifnet_llbroadcast_copy_bytes |
errno_t ifnet_llbroadcast_copy_bytes( ifnet_t interface, void*addr, size_t bufferlen, size_t*addr_len);
interfaceaddrbufferlenaddr_lenlladdr_lenRetrieves the link-layer broadcast address for this interface.
ifnet_metric |
u_int32_t ifnet_metric( ifnet_t interface);
interfaceThe metric.
ifnet_mtu |
u_int32_t ifnet_mtu( ifnet_t interface);
interfaceThe MTU.
ifnet_name |
const char* ifnet_name( ifnet_t interface);
interfacePointer to the name.
Returns a pointer to the name of the interface.
ifnet_offload |
ifnet_offload_t ifnet_offload( ifnet_t interface);
interfaceAbilities flags, see ifnet_offload_t.
Returns flags indicating which operations can be offloaded to the interface.
ifnet_output |
errno_t ifnet_output( ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet, void*route, const struct sockaddr *dest);
interfaceprotocol_familypacketroutedest0 on success otherwise the errno error.
Handles an outbound packet on the interface by calling any filters, a protocol preoutput function, the interface framer function, and finally the interface's output function. The protocol_family will be used to apply protocol filters and determine which preoutput function to call. The route and dest parameters will be passed to the preoutput function defined for the attachment of the specified protocol to the specified interface. ifnet_output will always free the mbuf chain.
ifnet_output_raw |
errno_t ifnet_output_raw( ifnet_t interface, protocol_family_t protocol_family, mbuf_t packet);
interfaceprotocol_familypacket0 on success otherwise the errno error.
Handles and outbond raw packet on the interface by calling any filters followed by the interface's output function. protocol_family may be zero. If the packet is from a specific protocol the protocol_family will be used to apply protocol filters. All interface filters will be applied to the outgoing packet. Processing, such as calling the protocol preoutput and interface framer functions will be bypassed. The packet will pass through the filters and be sent on the interface as is. ifnet_output_raw will always free the packet chain.
ifnet_reference |
errno_t ifnet_reference( ifnet_t interface);
interfaceMay return EINVAL if the interface is not valid.
Increment the reference count of the ifnet to assure that it will not go away. The interface must already have at least one reference.
ifnet_release |
errno_t ifnet_release( ifnet_t interface);
interfaceMay return EINVAL if the interface is not valid.
Release a reference of the ifnet, this may trigger a free if the reference count reaches 0.
ifnet_remove_multicast |
errno_t ifnet_remove_multicast( ifmultiaddr_t multicast);
multicast0 on success otherwise the errno error.
Causes the interface to leave the multicast group. The
stack keeps track of how many times ifnet_add_multicast has been
called for a given multicast address. The multicast will only be
removed when the number of times ifnet_remove_multicast has been
called matches the number of times ifnet_add_multicast has been
called.
The memory for the multicast address is not actually freed until
the separate reference count has reached zero. Some parts of the
stack may keep a pointer to the multicast even after that
multicast has been removed from the interface.
When an interface is detached, all of the multicasts are
removed. If the interface of the multicast passed in is no
longer attached, this function will gracefully return,
performing no work.
It is the callers responsibility to release the multicast
address after calling this function.
ifnet_resolve_multicast |
errno_t ifnet_resolve_multicast( ifnet_t ifp, const struct sockaddr *proto_addr, struct sockaddr *ll_addr, size_t ll_len);
interfaceproto_addrll_addrll_len0 on success. EOPNOTSUPP indicates the multicast address was not supported or could not be translated. Other errors may indicate other failures.
Resolves a multicast address for an attached protocol to a link-layer address. If a link-layer address is passed in, the interface will verify that it is a valid multicast address.
ifnet_set_addrlen |
errno_t ifnet_set_addrlen( ifnet_t interface, u_int8_t addrlen);
interfaceaddrlen0 on success otherwise the errno error.
This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.
ifnet_set_baudrate |
errno_t ifnet_set_baudrate( ifnet_t interface, u_int64_t baudrate);
interfacebaudrate0 on success otherwise the errno error.
This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.
ifnet_set_flags |
errno_t ifnet_set_flags( ifnet_t interface, u_int16_t new_flags, u_int16_t mask);
interfacenew_flags0 on success otherwise the errno error.
Sets the interface flags to new_flags. This function lets you specify which flags you want to change using the mask. The kernel will effectively take the lock, then set the interface's flags to (if_flags & ~mask) | (new_flags & mask).
ifnet_set_flags Sets the interface flags to match new_flags. |
errno_t ifnet_set_flags( ifnet_t interface, u_int16_t new_flags, u_int16_t mask);
interfacenew_flags0 on success otherwise the errno error.
Sets the interface flags to new_flags. This function lets you specify which flags you want to change using the mask. The kernel will effectively take the lock, then set the interface's flags to (if_flags & ~mask) | (new_flags & mask).
ifnet_set_hdrlen |
errno_t ifnet_set_hdrlen( ifnet_t interface, u_int8_t hdrlen);
interfacehdrlen0 on success otherwise the errno error.
This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.
ifnet_set_link_mib_data |
errno_t ifnet_set_link_mib_data( ifnet_t interface, void *mibData, u_int32_t mibLen);
interfacemibDatamibLen0 on success otherwise the errno error.
Sets the mib link data. The ifnet_t will store the
pointer you supply and copy mibLen bytes from the pointer
whenever the sysctl for getting interface specific MIB data is
used. Since the ifnet_t stores a pointer to your data instead of
a copy, you may update the data at the address at any time.
This function is intended to be called by the driver. A kext
must not call this function on an interface the kext does not
own.
ifnet_set_lladdr |
errno_t ifnet_set_lladdr( ifnet_t interface, const void*lladdr, size_t lladdr_len);
interfacelladdrlladdr_lenSets the link-layer address for this interface.
ifnet_set_metric |
errno_t ifnet_set_metric( ifnet_t interface, u_int32_t metric);
interfacemetric0 on success otherwise the errno error.
This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.
ifnet_set_mtu |
errno_t ifnet_set_mtu( ifnet_t interface, u_int32_t mtu);
interfacemtu0 on success otherwise the errno error.
Sets the value of the MTU in the interface structure.
Calling this function will not notify the driver that the MTU
should be changed. Use the appropriate ioctl.
This function is intended to be called by the driver. A kext
must not call this function on an interface the kext does not
own.
ifnet_set_offload |
errno_t ifnet_set_offload( ifnet_t interface, ifnet_offload_t offload);
interfaceoffloadmask0 on success otherwise the errno error.
Sets a bitfield to indicate special hardware offload support provided by the interface such as hardware checksums and VLAN. This replaces the if_hwassist flags field. Any flags unrecognized by the stack will not be set.
ifnet_set_promiscuous |
errno_t ifnet_set_promiscuous( ifnet_t interface, int on);
interfaceon0 on success otherwise the errno error.
Enable or disable promiscuous mode on the interface. The interface keeps an internal count of the number of times promiscuous mode has been enabled. Promiscuous mode is only disabled when this count reaches zero. Be sure to disable promiscuous mode only once for every time you enable it.
ifnet_set_stat |
errno_t ifnet_set_stat( ifnet_t interface, const struct ifnet_stats_param *stats);
interfacecounts0 on success otherwise the errno error.
This function is intended to be called by the driver. A kext
must not call this function on an interface the kext does not
own.
The one exception would be the case where a kext wants to zero
all of the counters.
ifnet_softc |
void* ifnet_softc( ifnet_t interface);
interfaceDriver's private storage.
Returns the driver's private storage on the interface.
ifnet_stat |
errno_t ifnet_stat( ifnet_t interface, struct ifnet_stats_param *out_stats);
interfaceout_stats0 on success otherwise the errno error.
ifnet_stat_increment |
errno_t ifnet_stat_increment( ifnet_t interface, const struct ifnet_stat_increment_param *counts);
interfacecounts0 on success otherwise the errno error.
This function is intended to be called by the driver. A kext must not call this function on an interface the kext does not own.
ifnet_stat_increment_in |
errno_t ifnet_stat_increment_in( ifnet_t interface, u_int32_t packets_in, u_int32_t bytes_in, u_int32_t errors_in);
interfacepackets_inbytes_inerrors_in0 on success otherwise the errno error.
This function is intended to be called by the driver. This
function allows a driver to update the inbound interface counts.
The most efficient time to update these counts is when calling
ifnet_input.
A lock protects the counts, this makes the increment functions
expensive. The increment function will update the lastchanged
value.
ifnet_stat_increment_out |
errno_t ifnet_stat_increment_out( ifnet_t interface, u_int32_t packets_out, u_int32_t bytes_out, u_int32_t errors_out);
interfacepackets_outbytes_outerrors_out0 on success otherwise the errno error.
This function is intended to be called by the driver. This
function allows a driver to update the outbound interface counts.
A lock protects the counts, this makes the increment functions
expensive. The increment function will update the lastchanged
value.
ifnet_touch_lastchange |
errno_t ifnet_touch_lastchange( ifnet_t interface);
interface0 on success otherwise the errno error.
Updates the lastchange value to now.
ifnet_type |
u_int8_t ifnet_type( ifnet_t interface);
interfaceThe type. See net/if_types.h.
ifnet_unit |
u_int32_t ifnet_unit( ifnet_t interface);
interfaceUnit number.
Returns the unit number of the interface.
bpf_packet_func |
/* Fast path - do not block or spend excessive amounts of time */ typedef errno_t (*bpf_packet_func)( ifnet_t interface, mbuf_t data);
interface- The interface being sent or received on.
data- The packet to be transmitted or received.
An errno value or zero upon success.
bpf_packet_func The bpf_packet_func is used to intercept inbound and outbound packets. The tap function will never free the mbuf. The tap function will only copy the mbuf in to various bpf file descriptors tapping this interface.
bpf_tap_mode |
Mode for tapping. BPF_MODE_DISABLED/BPF_MODE_INPUT_OUTPUT etc.
typedef u_int32_t bpf_tap_mode;
if_del_proto_func |
- ifnet_del_proto_func
typedef errno_t (*ifnet_del_proto_func)( ifnet_t interface, protocol_family_t protocol_family);
interface- The interface the protocol will be detached from.
protocol_family- The family of the protocol being detached.
If the result is zero, processing will continue normally. If the result is anything else, the detach will continue and the error will be returned to the caller.
if_del_proto_func is called by the stack when a protocol is being detached from an interface. This gives the interface an opportunity to free any storage related to this specific protocol being attached to this interface.
ifnet_add_proto_func |
typedef errno_t (*ifnet_add_proto_func)( ifnet_t interface, protocol_family_t protocol_family, const struct ifnet_demux_desc *demux_array, u_int32_t demux_count);
interface- The interface the protocol will be attached to.
protocol_family- The family of the protocol being attached.
demux_array- An array of demux descriptors that describe the interface specific ways of identifying packets belonging to this protocol family.
demux_count- The number of demux descriptors in the array.
If the result is zero, processing will continue normally. If the result is anything else, the add protocol will be aborted.
if_add_proto_func is called by the stack when a protocol is attached to an interface. This gives the interface an opportunity to get a list of protocol description structures for demuxing packets to this protocol (demux descriptors).
ifnet_check_multi |
typedef errno_t (*ifnet_check_multi)( ifnet_t interface, const struct sockaddr*mcast);
The- interface.
mcast- The multicast address.
Zero upon success, EADDRNOTAVAIL on invalid multicast, EOPNOTSUPP for addresses the interface does not understand.
ifnet_check_multi is called for each multicast address
added to an interface. This gives the interface an opportunity
to reject invalid multicast addresses before they are attached
to the interface.
To prevent an address from being added to your multicast list,
return EADDRNOTAVAIL. If you don't know how to parse/translate
the address, return EOPNOTSUPP.
ifnet_del_proto_func |
- if_del_proto_func
typedef errno_t (*ifnet_del_proto_func)( ifnet_t interface, protocol_family_t protocol_family);
interface- The interface the protocol will be detached from.
protocol_family- The family of the protocol being detached.
if_del_proto_func is called by the stack when a protocol is being detached from an interface. This gives the interface an opportunity to free any storage related to this specific protocol being attached to this interface.
ifnet_demux_func |
typedef errno_t (*ifnet_demux_func)( ifnet_t interface, mbuf_t packet, char *frame_header, protocol_family_t *protocol_family);
interface- The interface the packet was received on.
packet- The mbuf containing the packet.
frame_header- A pointer to the frame header.
protocol_family- Upon return, the protocol family matching the packet should be stored here.
If the result is zero, processing will continue normally. If the result is EJUSTRETURN, processing will stop but the packet will not be freed. If the result is anything else, the processing will stop and the packet will be freed.
ifnet_demux_func is called for each inbound packet to determine which protocol family the packet belongs to. This information is then used by the stack to determine which protocol to pass the packet to. This function may return protocol families for protocols that are not attached. If the protocol family has not been attached to the interface, the packet will be discarded.
ifnet_detached_func |
typedef void (*ifnet_detached_func)( ifnet_t interface);
interface- The interface that has been detached. event.
ifnet_detached_func is called an interface is detached from the list of interfaces. When ifnet_detach is called, it may not detach the interface immediately if protocols are attached. ifnet_detached_func is used to notify the interface that it has been detached from the networking stack. This is the last function that will be called on an interface. Until this function returns, you must not unload a kext supplying function pointers to this interface, even if ifnet_detacah has been called. Your detach function may be called during your call to ifnet_detach.
ifnet_event_func |
typedef void (*ifnet_event_func)( ifnet_t interface, const struct kev_msg *msg);
interface- The interface the event occurred on.
event_ptr- Pointer to a kern_event structure describing the event.
ifnet_event_func is called when an event occurs on a specific interface.
ifnet_family_t |
Storage type for the interface family.
typedef u_int32_t ifnet_family_t;
ifnet_framer_func |
typedef errno_t (*ifnet_framer_func)( ifnet_t interface, mbuf_t *packet, const struct sockaddr *dest, const char *desk_linkaddr, const char *frame_type);
interface- The interface the packet is being sent on.
packet- Pointer to the mbuf containing the packet, caller may set this to a different mbuf upon return. This can happen if the frameout function needs to prepend another mbuf to the chain to have enough space for the header.
dest- The higher layer protocol destination (i.e. IP address).
dest_linkaddr- The link layer address as determined by the protocol's pre-output function.
frame_type- The frame type as determined by the protocol's pre-output function.
If the result is zero, processing will continue normally. If the result is EJUSTRETURN, processing will stop but the packet will not be freed. If the result is anything else, the processing will stop and the packet will be freed.
ifnet_framer_func is called for each outbound packet to give the interface an opportunity to prepend interface specific headers.
ifnet_ioctl_func |
typedef errno_t (*ifnet_ioctl_func)( ifnet_t interface, u_int32_t cmd, void *data);
interface- The interface the ioctl is being sent to.
proto_family- The protocol family to handle the ioctl, may be zero for no protocol_family.
cmd- The ioctl command.
data- A pointer to any data related to the ioctl.
ifnet_ioctl_func is used to communicate ioctls from the
stack to the driver.
All undefined ioctls are reserved for future use by Apple. If
you need to communicate with your kext using an ioctl, please
use SIOCSIFKPI and SIOCGIFKPI.
ifnet_offload_t |
Flags indicating the offload support of the interface.
typedef u_int32_t ifnet_offload_t;
ifnet_output_func |
/* Fast path - do not block or spend excessive amounts of time */ typedef errno_t (*ifnet_output_func)( ifnet_t interface, mbuf_t data);
interface- The interface being sent on.
data- The packet to be sent.
ifnet_output_func is used to transmit packets. The stack will pass fully formed packets, including frame header, to the ifnet_output function for an interface. The driver is responsible for freeing the mbuf.
ifnet_set_bpf_tap |
typedef errno_t (*ifnet_set_bpf_tap)( ifnet_t interface, bpf_tap_mode mode, bpf_packet_func callback);
Deprecated. Specify NULL. Call bpf_tap_in/bpf_tap_out for all packets.
proto_media_detached |
typedef errno_t (*proto_media_detached)( ifnet_t ifp, protocol_family_t protocol);
ifp- The interface.
protocol_family- The protocol family.
See the discussion.
proto_media_detached notifies you that your protocol has been detached.
proto_media_event |
typedef void (*proto_media_event)( ifnet_t ifp, protocol_family_t protocol, const struct kev_msg *event);
ifp- The interface.
protocol_family- The protocol family.
kev_msg- The event.
proto_media_event is called to notify this layer of interface specific events.
proto_media_input |
typedef errno_t (*proto_media_input)( ifnet_t ifp, protocol_family_t protocol, mbuf_t packet, char*header);
ifp- The interface the packet was received on.
protocol_family- The protocol of the packet received.
packet- The packet being input.
header- The frame header.
If the result is zero, the caller will assume the packet was passed to the protocol. If the result is non-zero and not EJUSTRETURN, the caller will free the packet.
proto_media_input is called for all inbound packets for a specific protocol on a specific interface. This function is registered on an interface using ifnet_attach_protocol.
proto_media_ioctl |
typedef errno_t (*proto_media_ioctl)( ifnet_t ifp, protocol_family_t protocol, u_int32_t command, void*argument);
ifp- The interface.
protocol_family- The protocol family.
command- The ioctl command.
argument- The argument to the ioctl.
See the discussion.
proto_media_event allows this layer to handle ioctls.
When an ioctl is handled, it is passed to the interface filters,
protocol filters, protocol, and interface. If you do not support
this ioctl, return EOPNOTSUPP. If you successfully handle the
ioctl, return zero. If you return any error other than
EOPNOTSUPP, other parts of the stack may not get an opportunity
to process the ioctl. If you return EJUSTRETURN, processing will
stop and a result of zero will be returned to the caller.
All undefined ioctls are reserved for future use by Apple. If
you need to communicate with your kext using an ioctl, please
use SIOCSIFKPI and SIOCGIFKPI.
proto_media_preout |
typedef errno_t (*proto_media_preout)( ifnet_t ifp, protocol_family_t protocol, mbuf_t *packet, const struct sockaddr *dest, void *route, char *frame_type, char *link_layer_dest);
ifp- The interface the packet will be sent on.
protocol_family- The protocol of the packet being sent (PF_INET/etc...).
packet- The packet being sent.
dest- The protocol level destination address.
route- A pointer to the routing structure for the packet.
frame_type- The media specific frame type.
link_layer_dest- The media specific destination.
If the result is zero, processing will continue normally. If the result is non-zero, processing will stop. If the result is non-zero and not EJUSTRETURN, the packet will be freed by the caller.
proto_media_preout is called just before the packet is transmitted. This gives the proto_media_preout function an opportunity to specify the media specific frame type and destination.
proto_media_resolve_multi |
typedef errno_t (*proto_media_resolve_multi)( ifnet_t ifp, const struct sockaddr *proto_addr, struct sockaddr_dl *out_ll, size_t ll_len);
ifp- The interface.
proto_addr- The protocol address.
out_ll- A sockaddr_dl to copy the link layer multicast in to.
ll_len- The length of data allocated for out_ll.
Return zero on success or an errno error value on failure.
proto_media_resolve_multi is called to resolve a protocol layer mulitcast address to a link layer multicast address.
proto_media_send_arp |
typedef errno_t (*proto_media_send_arp)( ifnet_t ifp, u_short arpop, const struct sockaddr_dl*sender_hw, const struct sockaddr*sender_proto, const struct sockaddr_dl*target_hw, const struct sockaddr*target_proto);
ifp- The interface the arp packet should be sent on.
protocol_family- The protocol family of the addresses (PF_INET).
arpop- The arp operation (usually ARPOP_REQUEST or ARPOP_REPLY).
sender_hw- The value to use for the sender hardware address field. If this is NULL, use the hardware address of the interface.
sender_proto- The value to use for the sender protocol address field. This will not be NULL.
target_hw- The value to use for the target hardware address. If this is NULL, the target hardware address in the ARP packet should be NULL and the link-layer destination for the back should be a broadcast. If this is not NULL, this value should be used for both the link-layer destination and the target hardware address.
target_proto- The target protocol address. This will not be NULL.
Return zero on success or an errno error value on failure.
proto_media_send_arp is called by the stack to generate an ARP packet. This field is currently only used with IP. This function should inspect the parameters and transmit an arp packet using the information passed in.
protocol_family_t |
Storage type for the protocol family.
typedef u_int32_t protocol_family_t;
ifnet_attach_proto_param |
struct ifnet_attach_proto_param { struct ifnet_demux_desc *demux_array; /* interface may/may not require */ u_int32_t demux_count; /* interface may/may not require */ proto_media_input input; /* required */ proto_media_preout pre_output; /* required */ proto_media_event event; /* optional */ proto_media_ioctl ioctl; /* optional */ proto_media_detached detached; /* optional */ proto_media_resolve_multi resolve; /* optional */ proto_media_send_arp send_arp; /* optional */ };
demux_array- An array of ifnet_demux_desc structures describing the protocol.
demux_count- The number of entries in the demux_array array.
input- The function to be called for inbound packets.
pre_output- The function to be called for outbound packets.
event- The function to be called for interface events.
ioctl- The function to be called for ioctls.
detached- The function to be called for handling the detach.
This structure is used to attach a protocol to an interface. This structure provides the various functions for handling operations related to the protocol on the interface as well as information for how to demux packets for this protocol.
ifnet_demux_desc |
struct ifnet_demux_desc { u_int32_t type; void*data; u_int32_t datalen; };
type- The type of identifier data (i.e. ETHER_DESC_ETYPE2)
data- A pointer to an entry of type (i.e. pointer to 0x0800).
datalen- The number of bytes of data used to describe the packet.
This structure is to identify packets that belong to a specific protocol. The types supported are interface specific. Ethernet supports ETHER_DESC_ETYPE2, ETHER_DESC_SAP, and ETHER_DESC_SNAP. The type defines the offset in the packet where the data will be matched as well as context. For example, if ETHER_DESC_SNAP is specified, the only valid datalen is 5 and only in the 5 bytes will only be matched when the packet header indicates that the packet is a SNAP packet.
ifnet_init_params |
struct ifnet_init_params { /* used to match recycled interface */ const void*uniqueid; /* optional */ u_int32_t uniqueid_len; /* optional */ /* used to fill out initial values for interface */ const char*name; /* required */ u_int32_t unit; /* required */ ifnet_family_t family; /* required */ u_int32_t type; /* required */ ifnet_output_func output; /* required */ ifnet_demux_func demux; /* required */ ifnet_add_proto_func add_proto; /* required */ ifnet_del_proto_func del_proto; /* required */ ifnet_check_multi check_multi; /* required for non point-to-point interfaces */ ifnet_framer_func framer; /* optional */ void*softc; /* optional */ ifnet_ioctl_func ioctl; /* optional */ ifnet_set_bpf_tap set_bpf_tap; /* deprecated */ ifnet_detached_func detach; /* optional */ ifnet_event_func event; /* optional */ const void *broadcast_addr;/* required for non point-to-point interfaces */ u_int32_t broadcast_len; /* required for non point-to-point interfaces */ };
uniqueid- An identifier unique to this instance of the interface.
uniqueid_len- The length, in bytes, of the uniqueid.
name- The interface name (i.e. en).
unit- The interface unit number (en0's unit number is 0).
family- The interface family.
type- The interface type (see sys/if_types.h). Must be less than 256. For new types, use IFT_OTHER.
output- The output function for the interface. Every packet the stack attempts to send through this interface will go out through this function.
demux- The function used to determine the protocol family of an incoming packet.
add_proto- The function used to attach a protocol to this interface.
del_proto- The function used to remove a protocol from this interface.
framer- The function used to frame outbound packets, may be NULL.
softc- Driver specific storage. This value can be retrieved from the ifnet using the ifnet_softc function.
ioctl- The function used to handle ioctls.
set_bpf_tap- The function used to set the bpf_tap function.
detach- The function called to let the driver know the interface has been detached.
event- The function to notify the interface of various interface specific kernel events.
broadcast_addr- The link-layer broadcast address for this interface.
broadcast_len- The length of the link-layer broadcast address.
This structure is used to define various properties of the interface when calling ifnet_init. A copy of these values will be stored in the ifnet and can not be modified while the interface is attached.
ifnet_stat_increment_param |
struct ifnet_stat_increment_param { u_int32_t packets_in; u_int32_t bytes_in; u_int32_t errors_in; u_int32_t packets_out; u_int32_t bytes_out; u_int32_t errors_out; u_int32_t collisions; u_int32_t dropped; };
packets_in- The number of packets received.
bytes_in- The number of bytes received.
errors_in- The number of receive errors.
packets_out- The number of packets transmitted.
bytes_out- The number of bytes transmitted.
errors_out- The number of transmission errors.
collisions- The number of collisions seen by this interface.
dropped- The number of packets dropped.
This structure is used increment the counters on a network interface.
ifnet_stats_param |
struct ifnet_stats_param { u_int64_t packets_in; u_int64_t bytes_in; u_int64_t multicasts_in; u_int64_t errors_in; u_int64_t packets_out; u_int64_t bytes_out; u_int64_t multicasts_out; u_int64_t errors_out; u_int64_t collisions; u_int64_t dropped; u_int64_t no_protocol; };
packets_in- The number of packets received.
bytes_in- The number of bytes received.
errors_in- The number of receive errors.
packets_out- The number of packets transmitted.
bytes_out- The number of bytes transmitted.
errors_out- The number of transmission errors.
collisions- The number of collisions seen by this interface.
dropped- The number of packets dropped.
This structure is used get and set the interface statistics.
BPF |
Constants defining interface families.
enum { BPF_MODE_DISABLED = 0, BPF_MODE_INPUT = 1, BPF_MODE_OUTPUT = 2, BPF_MODE_INPUT_OUTPUT = 3 };
BPF_MODE_DISABLED- Disable bpf.
BPF_MODE_INPUT- Enable input only.
BPF_MODE_OUTPUT- Enable output only.
BPF_MODE_INPUT_OUTPUT- Enable input and output.
tap mode
Interface |
Constants defining interface families.
enum { IFNET_FAMILY_ANY = 0, IFNET_FAMILY_LOOPBACK = 1, IFNET_FAMILY_ETHERNET = 2, IFNET_FAMILY_SLIP = 3, IFNET_FAMILY_TUN = 4, IFNET_FAMILY_VLAN = 5, IFNET_FAMILY_PPP = 6, IFNET_FAMILY_PVC = 7, IFNET_FAMILY_DISC = 8, IFNET_FAMILY_MDECAP = 9, IFNET_FAMILY_GIF = 10, IFNET_FAMILY_FAITH = 11, IFNET_FAMILY_STF = 12, IFNET_FAMILY_FIREWIRE = 13, IFNET_FAMILY_BOND = 14 };
IFNET_FAMILY_ANY- Match interface of any family type.
IFNET_FAMILY_LOOPBACK- A software loopback interface.
IFNET_FAMILY_ETHERNET- An Ethernet interface.
IFNET_FAMILY_SLIP- A SLIP interface.
IFNET_FAMILY_TUN- A tunnel interface.
IFNET_FAMILY_VLAN- A virtual LAN interface.
IFNET_FAMILY_PPP- A PPP interface.
IFNET_FAMILY_PVC- A PVC interface.
IFNET_FAMILY_DISC- A DISC interface.
IFNET_FAMILY_MDECAP- A MDECAP interface.
IFNET_FAMILY_GIF- A generic tunnel interface.
IFNET_FAMILY_FAITH- A FAITH (IPv4/IPv6 translation) interface.
IFNET_FAMILY_STF- A 6to4 interface.
IFNET_FAMILY_FIREWIRE- An IEEE 1394 (firewire) interface.
IFNET_FAMILY_BOND- A virtual bonded interface.
Families
Interface |
Constants defining interface offload support.
enum { IFNET_CSUM_IP = 0x00000001, IFNET_CSUM_TCP = 0x00000002, IFNET_CSUM_UDP = 0x00000004, IFNET_CSUM_FRAGMENT = 0x00000008, IFNET_IP_FRAGMENT = 0x00000010, IFNET_VLAN_TAGGING = 0x00010000, IFNET_VLAN_MTU = 0x00020000, };
IFNET_CSUM_IP- Hardware will calculate IPv4 checksums.
IFNET_CSUM_TCP- Hardware will calculate TCP checksums.
IFNET_CSUM_UDP- Hardware will calculate UDP checksums.
IFNET_CSUM_FRAGMENT- Hardware will checksum IP fragments.
IFNET_IP_FRAGMENT- Hardware will fragment IP packets.
IFNET_VLAN_TAGGING- Hardware will generate VLAN headers.
IFNET_VLAN_MTU- Hardware supports VLAN MTU.
Abilities
|