Mac Developer Library

Developer

kpi_interfacefilter.h Reference

Options
Deployment Target:

On This Page

kpi_interfacefilter.h Reference

This header defines an API to attach interface filters. Interface filters may be attached to a specific interface. The filters can intercept all packets in to and out of the specific interface. In addition, the filters may intercept interface specific events and ioctls.

Included Headers

  • <sys/kernel_types.h>

  • <net/kpi_interface.h>

Functions

  • Declaration

    Objective-C

    errno_t iflt_attach ( ifnet_t interface, const struct iff_filter *filter, interface_filter_t *filter_ref );

    Parameters

    interface

    The interface the filter should be attached to.

    filter

    A structure defining the filter.

    filter_ref

    A reference to the filter used to detach.

    Return Value

    0 on success otherwise the errno error.

    Discussion

    Attaches an interface filter to an interface.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    void iflt_detach ( interface_filter_t filter_ref );

    Parameters

    filter_ref

    The reference to the filter from iflt_attach.

    Discussion

    Detaches an interface filter from an interface.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Declaration

    Objective-C

    typedef void ( *iff_detached_func)( void *cookie, ifnet_t interface);

    Parameters

    cookie

    The cookie specified when this filter was attached.

    interface

    The interface this filter was detached from.

    Discussion

    iff_detached_func is called to notify the filter that it has been detached from an interface. This is the last call to the filter that will be made. A filter may be detached if the interface is detached or the detach filter function is called. In the case that the interface is being detached, your filter's event function will be called with the interface detaching event before the your detached function will be called.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    typedef void ( *iff_event_func)( void *cookie, ifnet_t interface, protocol_family_t protocol, const struct kev_msg *event_msg);

    Parameters

    cookie

    The cookie specified when this filter was attached.

    interface

    The interface the packet is being transmitted on.

    event_msg

    The kernel event, may not be changed.

    Discussion

    iff_event_func is used to filter interface specific events. The interface is only valid for the duration of the filter call. If you need to keep a reference to the interface, be sure to call ifnet_reference and ifnet_release.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    typedef errno_t ( *iff_input_func)( void *cookie, ifnet_t interface, protocol_family_t protocol, mbuf_t *data, char **frame_ptr);

    Parameters

    cookie

    The cookie specified when this filter was attached.

    interface

    The interface the packet was recieved on.

    protocol

    The protocol of this packet. If you specified a protocol when attaching your filter, the protocol will only ever be the protocol you specified.

    data

    The inbound packet, after the frame header as determined by the interface.

    frame_ptr

    A pointer to the pointer to the frame header. The frame header length can be found by inspecting the interface's frame header length (ifnet_hdrlen).

    Return Value

    Return: 0 - The caller will continue with normal processing of the packet. EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed. Anything Else - The caller will free the packet and stop processing.

    Discussion

    iff_input_func is used to filter incoming packets. The interface is only valid for the duration of the filter call. If you need to keep a reference to the interface, be sure to call ifnet_reference and ifnet_release. The packets passed to the inbound filter are different from those passed to the outbound filter. Packets to the inbound filter have the frame header passed in separately from the rest of the packet. The outbound data filters is passed the whole packet including the frame header.

    The frame header usually preceeds the data in the mbuf. This ensures that the frame header will be a valid pointer as long as the mbuf is not freed. If you need to change the frame header to point somewhere else, the recommended method is to prepend a new frame header to the mbuf chain (mbuf_prepend), set the header to point to that data, then call mbuf_adj to move the mbuf data pointer back to the start of the packet payload.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    typedef errno_t ( *iff_ioctl_func)( void *cookie, ifnet_t interface, protocol_family_t protocol, unsigned long ioctl_cmd, void *ioctl_arg);

    Parameters

    cookie

    The cookie specified when this filter was attached.

    interface

    The interface the packet is being transmitted on.

    ioctl_cmd

    The ioctl command.

    ioctl_arg

    A pointer to the ioctl argument.

    Return Value

    Return: 0 - This filter function handled the ioctl. EOPNOTSUPP - This filter function does not understand/did not handle this ioctl. EJUSTRETURN - This filter function handled the ioctl, processing should stop. Anything Else - Processing will stop, the error will be returned.

    Discussion

    iff_ioctl_func is used to filter ioctls sent to an interface. The interface is only valid for the duration of the filter call. If you need to keep a reference to the interface, be sure to call ifnet_reference and ifnet_release.

    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.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    typedef errno_t ( *iff_output_func)( void *cookie, ifnet_t interface, protocol_family_t protocol, mbuf_t *data);

    Parameters

    cookie

    The cookie specified when this filter was attached.

    interface

    The interface the packet is being transmitted on.

    data

    The fully formed outbound packet in a chain of mbufs. The frame header is already included. The filter function may modify the packet or return a different mbuf chain.

    Return Value

    Return: 0 - The caller will continue with normal processing of the packet. EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed. Anything Else - The caller will free the packet and stop processing.

    Discussion

    iff_output_func is used to filter fully formed outbound packets. The interface is only valid for the duration of the filter call. If you need to keep a reference to the interface, be sure to call ifnet_reference and ifnet_release.

    Import Statement

    Objective-C

    #include <kpi_interfacefilter.h>;

    Availability

    Available in OS X v10.4 and later.

Data Types

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    struct iff_filter { void *iff_cookie; const char *iff_name; protocol_family_t iff_protocol; iff_input_func iff_input; iff_output_func iff_output; iff_event_func iff_event; iff_ioctl_func iff_ioctl; iff_detached_func iff_detached; };

    Fields

    iff_cookie

    A kext defined cookie that will be passed to all filter functions.

    iff_name

    A filter name used for debugging purposes.

    iff_protocol

    The protocol of the packets this filter is interested in. If you specify zero, packets from all protocols will be passed to the filter.

    iff_input

    The filter function to handle inbound packets, may be NULL.

    iff_output

    The filter function to handle outbound packets, may be NULL.

    iff_event

    The filter function to handle interface events, may be null.

    iff_ioctl

    The filter function to handle interface ioctls, may be null.

    iff_detached

    The filter function used to notify the filter that it has been detached.

    Discussion

    This structure is used to define an interface filter for use with the iflt_attach function.

    Availability

    Available in OS X v10.6 and later.