[apple/xnu.git] / bsd / net / kpi_interfacefilter.h

/*
 * Copyright (c) 2008 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*!
	@header kpi_interfacefilter.h
	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.
 */

#ifndef __KPI_INTERFACEFILTER__
#define __KPI_INTERFACEFILTER__
#include <sys/kernel_types.h>
#include <net/kpi_interface.h>

struct kev_msg;

__BEGIN_DECLS

/*!
	@typedef iff_input_func

	@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.
	@param cookie The cookie specified when this filter was attached.
	@param interface The interface the packet was recieved on.
	@param 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.
	@param data The inbound packet, after the frame header as determined
		by the interface.
	@param 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).
	@result 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.
*/
typedef	errno_t (*iff_input_func)(void *cookie, ifnet_t interface,
    protocol_family_t protocol, mbuf_t *data, char **frame_ptr);

/*!
	@typedef iff_output_func

	@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.
	@param cookie The cookie specified when this filter was attached.
	@param interface The interface the packet is being transmitted on.
	@param 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.
	@result 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.
*/
typedef	errno_t (*iff_output_func)(void *cookie, ifnet_t interface,
    protocol_family_t protocol, mbuf_t *data);

/*!
	@typedef iff_event_func

	@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.
	@param cookie The cookie specified when this filter was attached.
	@param interface The interface the packet is being transmitted on.
	@param event_msg The kernel event, may not be changed.
*/
typedef	void (*iff_event_func)(void *cookie, ifnet_t interface,
    protocol_family_t protocol, const struct kev_msg *event_msg);

/*!
	@typedef iff_ioctl_func

	@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.
	@param cookie The cookie specified when this filter was attached.
	@param interface The interface the packet is being transmitted on.
	@param ioctl_cmd The ioctl command.
	@param ioctl_arg A pointer to the ioctl argument.
	@result 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.
*/
typedef	errno_t (*iff_ioctl_func)(void *cookie, ifnet_t interface,
    protocol_family_t protocol, unsigned long ioctl_cmd, void *ioctl_arg);

/*!
	@typedef iff_detached_func

	@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.
	@param cookie The cookie specified when this filter was attached.
	@param interface The interface this filter was detached from.
*/
typedef	void (*iff_detached_func)(void *cookie, ifnet_t interface);

/*!
	@struct iff_filter
	@discussion This structure is used to define an interface filter for
		use with the iflt_attach function.
	@field iff_cookie A kext defined cookie that will be passed to all
		filter functions.
	@field iff_name A filter name used for debugging purposes.
	@field 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.
	@field iff_input The filter function to handle inbound packets, may
		be NULL.
	@field iff_output The filter function to handle outbound packets,
		may be NULL.
	@field iff_event The filter function to handle interface events, may
		be null.
	@field iff_ioctl The filter function to handle interface ioctls, may
		be null.
	@field iff_detached The filter function used to notify the filter that
		it has been detached.
*/

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;
};

/*!
	@function iflt_attach
	@discussion Attaches an interface filter to an interface.
	@param interface The interface the filter should be attached to.
	@param filter A structure defining the filter.
	@param filter_ref A reference to the filter used to detach.
	@result 0 on success otherwise the errno error.
 */
extern errno_t iflt_attach(ifnet_t interface, const struct iff_filter *filter,
    interface_filter_t *filter_ref);

/*!
	@function iflt_detach
	@discussion Detaches an interface filter from an interface.
	@param filter_ref The reference to the filter from iflt_attach.
 */
extern void iflt_detach(interface_filter_t filter_ref);

__END_DECLS
#endif /* __KPI_INTERFACEFILTER__ */
Commit	Line	Data
91447636	1	/*
b0d623f7	2	* Copyright (c) 2008 Apple Computer, Inc. All rights reserved.
5d5c5d0d	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
91447636	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.
8f6c56a5	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.
	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
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	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.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
91447636 A	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
2d21ac55 A	44	__BEGIN_DECLS
2d21ac55 A	45
91447636 A	46	/*!
91447636 A	47	@typedef iff_input_func
b0d623f7	48
91447636 A	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.
b0d623f7	58
91447636 A	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:
b0d623f7 A	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.
91447636	83	*/
b0d623f7 A	84	typedef errno_t (iff_input_func)(void cookie, ifnet_t interface,
b0d623f7 A	85	protocol_family_t protocol, mbuf_t data, char *frame_ptr);
91447636 A	86
	87	/*!
	88	@typedef iff_output_func
b0d623f7	89
91447636 A	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:
b0d623f7 A	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.
91447636	106	*/
b0d623f7 A	107	typedef errno_t (iff_output_func)(void cookie, ifnet_t interface,
b0d623f7 A	108	protocol_family_t protocol, mbuf_t *data);
91447636 A	109
	110	/*!
	111	@typedef iff_event_func
b0d623f7	112
91447636 A	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	*/
b0d623f7 A	121	typedef void (iff_event_func)(void cookie, ifnet_t interface,
b0d623f7 A	122	protocol_family_t protocol, const struct kev_msg *event_msg);
91447636 A	123
	124	/*!
	125	@typedef iff_ioctl_func
b0d623f7	126
91447636 A	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.
b0d623f7	131
2d21ac55 A	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.
91447636 A	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:
2d21ac55	140	0 - This filter function handled the ioctl.
b0d623f7 A	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.
91447636	147	*/
b0d623f7 A	148	typedef errno_t (iff_ioctl_func)(void cookie, ifnet_t interface,
b0d623f7 A	149	protocol_family_t protocol, unsigned long ioctl_cmd, void *ioctl_arg);
91447636 A	150
	151	/*!
	152	@typedef iff_detached_func
b0d623f7	153
91447636 A	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	*/
b0d623f7	164	typedef void (iff_detached_func)(void cookie, ifnet_t interface);
91447636 A	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 {
b0d623f7 A	189	void *iff_cookie;
b0d623f7 A	190	const char *iff_name;
91447636 A	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	*/
b0d623f7 A	207	extern errno_t iflt_attach(ifnet_t interface, const struct iff_filter *filter,
b0d623f7 A	208	interface_filter_t *filter_ref);
91447636 A	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	*/
b0d623f7	215	extern void iflt_detach(interface_filter_t filter_ref);
6601e61a	216
2d21ac55	217	__END_DECLS
b0d623f7	218	#endif /* __KPI_INTERFACEFILTER__ */