]>
Commit | Line | Data |
---|---|---|
91447636 | 1 | /* |
5ba3f43e | 2 | * Copyright (c) 2003,2008,2017 Apple Computer, Inc. All rights reserved. |
5d5c5d0d | 3 | * |
2d21ac55 | 4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
0a7de745 | 5 | * |
2d21ac55 A |
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. | |
0a7de745 | 14 | * |
2d21ac55 A |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. | |
0a7de745 | 17 | * |
2d21ac55 A |
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 | |
8f6c56a5 A |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, | |
2d21ac55 A |
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. | |
0a7de745 | 25 | * |
2d21ac55 | 26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
91447636 A |
27 | */ |
28 | /*! | |
0a7de745 A |
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. | |
91447636 A |
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 | ||
2d21ac55 A |
44 | __BEGIN_DECLS |
45 | ||
91447636 | 46 | /*! |
0a7de745 A |
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, | |
b0d623f7 | 85 | protocol_family_t protocol, mbuf_t *data, char **frame_ptr); |
91447636 A |
86 | |
87 | /*! | |
0a7de745 A |
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, | |
b0d623f7 | 108 | protocol_family_t protocol, mbuf_t *data); |
91447636 A |
109 | |
110 | /*! | |
0a7de745 A |
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, | |
b0d623f7 | 122 | protocol_family_t protocol, const struct kev_msg *event_msg); |
91447636 A |
123 | |
124 | /*! | |
0a7de745 A |
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, | |
b0d623f7 | 149 | protocol_family_t protocol, unsigned long ioctl_cmd, void *ioctl_arg); |
91447636 A |
150 | |
151 | /*! | |
0a7de745 A |
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); | |
91447636 A |
165 | |
166 | /*! | |
0a7de745 A |
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 | */ | |
91447636 A |
187 | |
188 | struct iff_filter { | |
0a7de745 A |
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; | |
91447636 A |
197 | }; |
198 | ||
199 | /*! | |
0a7de745 A |
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. | |
91447636 | 206 | */ |
5ba3f43e A |
207 | #ifdef KERNEL_PRIVATE |
208 | extern errno_t iflt_attach_internal(ifnet_t interface, const struct iff_filter *filter, | |
209 | interface_filter_t *filter_ref); | |
210 | ||
211 | #define iflt_attach(interface, filter, filter_ref) \ | |
212 | iflt_attach_internal((interface), (filter), (filter_ref)) | |
213 | #else | |
b0d623f7 A |
214 | extern errno_t iflt_attach(ifnet_t interface, const struct iff_filter *filter, |
215 | interface_filter_t *filter_ref); | |
5ba3f43e | 216 | #endif /* KERNEL_PRIVATE */ |
91447636 A |
217 | |
218 | /*! | |
0a7de745 A |
219 | * @function iflt_detach |
220 | * @discussion Detaches an interface filter from an interface. | |
221 | * @param filter_ref The reference to the filter from iflt_attach. | |
91447636 | 222 | */ |
b0d623f7 | 223 | extern void iflt_detach(interface_filter_t filter_ref); |
6601e61a | 224 | |
2d21ac55 | 225 | __END_DECLS |
b0d623f7 | 226 | #endif /* __KPI_INTERFACEFILTER__ */ |