]> git.saurik.com Git - apple/xnu.git/blame - bsd/net/kpi_interfacefilter.h
xnu-6153.41.3.tar.gz
[apple/xnu.git] / bsd / net / kpi_interfacefilter.h
CommitLineData
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
42struct 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 */
84typedef 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 */
107typedef 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 */
121typedef 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 */
148typedef 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 */
164typedef 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
188struct 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
208extern 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
214extern 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 223extern void iflt_detach(interface_filter_t filter_ref);
6601e61a 224
2d21ac55 225__END_DECLS
b0d623f7 226#endif /* __KPI_INTERFACEFILTER__ */