bsd/net/kpi_interfacefilter.h

   1 /*
   2  * Copyright (c) 2008 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*!
  29         @header kpi_interfacefilter.h
  30         This header defines an API to attach interface filters. Interface
  31         filters may be attached to a specific interface. The filters can
  32         intercept all packets in to and out of the specific interface. In
  33         addition, the filters may intercept interface specific events and
  34         ioctls.
  35  */
  36
  37 #ifndef __KPI_INTERFACEFILTER__
  38 #define __KPI_INTERFACEFILTER__
  39 #include <sys/kernel_types.h>
  40 #include <net/kpi_interface.h>
  41
  42 struct kev_msg;
  43
  44 __BEGIN_DECLS
  45
  46 /*!
  47         @typedef iff_input_func
  48
  49         @discussion iff_input_func is used to filter incoming packets. The
  50                 interface is only valid for the duration of the filter call. If
  51                 you need to keep a reference to the interface, be sure to call
  52                 ifnet_reference and ifnet_release. The packets passed to the
  53                 inbound filter are different from those passed to the outbound
  54                 filter. Packets to the inbound filter have the frame header
  55                 passed in separately from the rest of the packet. The outbound
  56                 data filters is passed the whole packet including the frame
  57                 header.
  58
  59                 The frame header usually preceeds the data in the mbuf. This
  60                 ensures that the frame header will be a valid pointer as long as
  61                 the mbuf is not freed. If you need to change the frame header to
  62                 point somewhere else, the recommended method is to prepend a new
  63                 frame header to the mbuf chain (mbuf_prepend), set the header to
  64                 point to that data, then call mbuf_adj to move the mbuf data
  65                 pointer back to the start of the packet payload.
  66         @param cookie The cookie specified when this filter was attached.
  67         @param interface The interface the packet was recieved on.
  68         @param protocol The protocol of this packet. If you specified a
  69                 protocol when attaching your filter, the protocol will only ever
  70                 be the protocol you specified.
  71         @param data The inbound packet, after the frame header as determined
  72                 by the interface.
  73         @param frame_ptr A pointer to the pointer to the frame header. The
  74                 frame header length can be found by inspecting the interface's
  75                 frame header length (ifnet_hdrlen).
  76         @result Return:
  77                 0 - The caller will continue with normal processing of the
  78                         packet.
  79                 EJUSTRETURN - The caller will stop processing the packet,
  80                         the packet will not be freed.
  81                 Anything Else - The caller will free the packet and stop
  82                         processing.
  83 */
  84 typedef errno_t (*iff_input_func)(void *cookie, ifnet_t interface,
  85     protocol_family_t protocol, mbuf_t *data, char **frame_ptr);
  86
  87 /*!
  88         @typedef iff_output_func
  89
  90         @discussion iff_output_func is used to filter fully formed outbound
  91                 packets. The interface is only valid for the duration of the
  92                 filter call. If you need to keep a reference to the interface,
  93                 be sure to call ifnet_reference and ifnet_release.
  94         @param cookie The cookie specified when this filter was attached.
  95         @param interface The interface the packet is being transmitted on.
  96         @param data The fully formed outbound packet in a chain of mbufs.
  97                 The frame header is already included. The filter function may
  98                 modify the packet or return a different mbuf chain.
  99         @result Return:
 100                 0 - The caller will continue with normal processing of the
 101                         packet.
 102                 EJUSTRETURN - The caller will stop processing the packet,
 103                         the packet will not be freed.
 104                 Anything Else - The caller will free the packet and stop
 105                         processing.
 106 */
 107 typedef errno_t (*iff_output_func)(void *cookie, ifnet_t interface,
 108     protocol_family_t protocol, mbuf_t *data);
 109
 110 /*!
 111         @typedef iff_event_func
 112
 113         @discussion iff_event_func is used to filter interface specific
 114                 events. The interface is only valid for the duration of the
 115                 filter call. If you need to keep a reference to the interface,
 116                 be sure to call ifnet_reference and ifnet_release.
 117         @param cookie The cookie specified when this filter was attached.
 118         @param interface The interface the packet is being transmitted on.
 119         @param event_msg The kernel event, may not be changed.
 120 */
 121 typedef void (*iff_event_func)(void *cookie, ifnet_t interface,
 122     protocol_family_t protocol, const struct kev_msg *event_msg);
 123
 124 /*!
 125         @typedef iff_ioctl_func
 126
 127         @discussion iff_ioctl_func is used to filter ioctls sent to an
 128                 interface. The interface is only valid for the duration of the
 129                 filter call. If you need to keep a reference to the interface,
 130                 be sure to call ifnet_reference and ifnet_release.
 131
 132                 All undefined ioctls are reserved for future use by Apple. If
 133                 you need to communicate with your kext using an ioctl, please
 134                 use SIOCSIFKPI and SIOCGIFKPI.
 135         @param cookie The cookie specified when this filter was attached.
 136         @param interface The interface the packet is being transmitted on.
 137         @param ioctl_cmd The ioctl command.
 138         @param ioctl_arg A pointer to the ioctl argument.
 139         @result Return:
 140                 0 - This filter function handled the ioctl.
 141                 EOPNOTSUPP - This filter function does not understand/did not
 142                         handle this ioctl.
 143                 EJUSTRETURN - This filter function handled the ioctl,
 144                         processing should stop.
 145                 Anything Else - Processing will stop, the error will be
 146                         returned.
 147 */
 148 typedef errno_t (*iff_ioctl_func)(void *cookie, ifnet_t interface,
 149     protocol_family_t protocol, unsigned long ioctl_cmd, void *ioctl_arg);
 150
 151 /*!
 152         @typedef iff_detached_func
 153
 154         @discussion iff_detached_func is called to notify the filter that it
 155                 has been detached from an interface. This is the last call to
 156                 the filter that will be made. A filter may be detached if the
 157                 interface is detached or the detach filter function is called.
 158                 In the case that the interface is being detached, your filter's
 159                 event function will be called with the interface detaching event
 160                 before the your detached function will be called.
 161         @param cookie The cookie specified when this filter was attached.
 162         @param interface The interface this filter was detached from.
 163 */
 164 typedef void (*iff_detached_func)(void *cookie, ifnet_t interface);
 165
 166 /*!
 167         @struct iff_filter
 168         @discussion This structure is used to define an interface filter for
 169                 use with the iflt_attach function.
 170         @field iff_cookie A kext defined cookie that will be passed to all
 171                 filter functions.
 172         @field iff_name A filter name used for debugging purposes.
 173         @field iff_protocol The protocol of the packets this filter is
 174                 interested in. If you specify zero, packets from all protocols
 175                 will be passed to the filter.
 176         @field iff_input The filter function to handle inbound packets, may
 177                 be NULL.
 178         @field iff_output The filter function to handle outbound packets,
 179                 may be NULL.
 180         @field iff_event The filter function to handle interface events, may
 181                 be null.
 182         @field iff_ioctl The filter function to handle interface ioctls, may
 183                 be null.
 184         @field iff_detached The filter function used to notify the filter that
 185                 it has been detached.
 186 */
 187
 188 struct iff_filter {
 189         void                    *iff_cookie;
 190         const char              *iff_name;
 191         protocol_family_t       iff_protocol;
 192         iff_input_func          iff_input;
 193         iff_output_func         iff_output;
 194         iff_event_func          iff_event;
 195         iff_ioctl_func          iff_ioctl;
 196         iff_detached_func       iff_detached;
 197 };
 198
 199 /*!
 200         @function iflt_attach
 201         @discussion Attaches an interface filter to an interface.
 202         @param interface The interface the filter should be attached to.
 203         @param filter A structure defining the filter.
 204         @param filter_ref A reference to the filter used to detach.
 205         @result 0 on success otherwise the errno error.
 206  */
 207 extern errno_t iflt_attach(ifnet_t interface, const struct iff_filter *filter,
 208     interface_filter_t *filter_ref);
 209
 210 /*!
 211         @function iflt_detach
 212         @discussion Detaches an interface filter from an interface.
 213         @param filter_ref The reference to the filter from iflt_attach.
 214  */
 215 extern void iflt_detach(interface_filter_t filter_ref);
 216
 217 __END_DECLS
 218 #endif /* __KPI_INTERFACEFILTER__ */