1/* 2 * Copyright (c) 2003 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 42struct 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 packet. 78 EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed. 79 Anything Else - The caller will free the packet and stop processing. 80*/ 81typedef errno_t (*iff_input_func)(void* cookie, ifnet_t interface, protocol_family_t protocol, 82 mbuf_t *data, char **frame_ptr); 83 84/*! 85 @typedef iff_output_func 86 87 @discussion iff_output_func is used to filter fully formed outbound 88 packets. The interface is only valid for the duration of the 89 filter call. If you need to keep a reference to the interface, 90 be sure to call ifnet_reference and ifnet_release. 91 @param cookie The cookie specified when this filter was attached. 92 @param interface The interface the packet is being transmitted on. 93 @param data The fully formed outbound packet in a chain of mbufs. 94 The frame header is already included. The filter function may 95 modify the packet or return a different mbuf chain. 96 @result Return: 97 0 - The caller will continue with normal processing of the packet. 98 EJUSTRETURN - The caller will stop processing the packet, the packet will not be freed. 99 Anything Else - The caller will free the packet and stop processing. 100*/ 101typedef errno_t (*iff_output_func)(void* cookie, ifnet_t interface, protocol_family_t protocol, 102 mbuf_t *data); 103 104/*! 105 @typedef iff_event_func 106 107 @discussion iff_event_func is used to filter interface specific 108 events. The interface is only valid for the duration of the 109 filter call. If you need to keep a reference to the interface, 110 be sure to call ifnet_reference and ifnet_release. 111 @param cookie The cookie specified when this filter was attached. 112 @param interface The interface the packet is being transmitted on. 113 @param event_msg The kernel event, may not be changed. 114*/ 115typedef void (*iff_event_func)(void* cookie, ifnet_t interface, protocol_family_t protocol, 116 const struct kev_msg *event_msg); 117 118/*! 119 @typedef iff_ioctl_func 120 121 @discussion iff_ioctl_func is used to filter ioctls sent to an 122 interface. The interface is only valid for the duration of the 123 filter call. If you need to keep a reference to the interface, 124 be sure to call ifnet_reference and ifnet_release. 125 126 All undefined ioctls are reserved for future use by Apple. If 127 you need to communicate with your kext using an ioctl, please 128 use SIOCSIFKPI and SIOCGIFKPI. 129 @param cookie The cookie specified when this filter was attached. 130 @param interface The interface the packet is being transmitted on. 131 @param ioctl_cmd The ioctl command. 132 @param ioctl_arg A pointer to the ioctl argument. 133 @result Return: 134 0 - This filter function handled the ioctl. 135 EOPNOTSUPP - This filter function does not understand/did not handle this ioctl. 136 EJUSTRETURN - This filter function handled the ioctl, processing should stop. 137 Anything Else - Processing will stop, the error will be returned. 138*/ 139typedef errno_t (*iff_ioctl_func)(void* cookie, ifnet_t interface, protocol_family_t protocol, 140 u_long ioctl_cmd, void* ioctl_arg); 141 142/*! 143 @typedef iff_detached_func 144 145 @discussion iff_detached_func is called to notify the filter that it 146 has been detached from an interface. This is the last call to 147 the filter that will be made. A filter may be detached if the 148 interface is detached or the detach filter function is called. 149 In the case that the interface is being detached, your filter's 150 event function will be called with the interface detaching event 151 before the your detached function will be called. 152 @param cookie The cookie specified when this filter was attached. 153 @param interface The interface this filter was detached from. 154*/ 155typedef void (*iff_detached_func)(void* cookie, ifnet_t interface); 156 157/*! 158 @struct iff_filter 159 @discussion This structure is used to define an interface filter for 160 use with the iflt_attach function. 161 @field iff_cookie A kext defined cookie that will be passed to all 162 filter functions. 163 @field iff_name A filter name used for debugging purposes. 164 @field iff_protocol The protocol of the packets this filter is 165 interested in. If you specify zero, packets from all protocols 166 will be passed to the filter. 167 @field iff_input The filter function to handle inbound packets, may 168 be NULL. 169 @field iff_output The filter function to handle outbound packets, 170 may be NULL. 171 @field iff_event The filter function to handle interface events, may 172 be null. 173 @field iff_ioctl The filter function to handle interface ioctls, may 174 be null. 175 @field iff_detached The filter function used to notify the filter that 176 it has been detached. 177*/ 178 179struct iff_filter { 180 void* iff_cookie; 181 const char* iff_name; 182 protocol_family_t iff_protocol; 183 iff_input_func iff_input; 184 iff_output_func iff_output; 185 iff_event_func iff_event; 186 iff_ioctl_func iff_ioctl; 187 iff_detached_func iff_detached; 188}; 189 190/*! 191 @function iflt_attach 192 @discussion Attaches an interface filter to an interface. 193 @param interface The interface the filter should be attached to. 194 @param filter A structure defining the filter. 195 @param filter_ref A reference to the filter used to detach. 196 @result 0 on success otherwise the errno error. 197 */ 198errno_t iflt_attach(ifnet_t interface, const struct iff_filter* filter, 199 interface_filter_t *filter_ref); 200 201/*! 202 @function iflt_detach 203 @discussion Detaches an interface filter from an interface. 204 @param filter_ref The reference to the filter from iflt_attach. 205 */ 206void iflt_detach(interface_filter_t filter_ref); 207 208__END_DECLS 209#endif 210