device_set_filter.html [plain text]
<h2>device_set_filter</h2>
<hr>
<p>
<strong>Function</strong> - Name an input filter for a device.
<h3>SYNOPSIS</h3>
<pre>
<strong>#include< device/device.h></strong>
<strong>#include< device/net_status.h></strong>
<strong>kern_return_t device_set_filter</strong>
<strong>(mach_port_t</strong> <var>device</var>,
<strong>mach_port_t</strong> <var>receive_port</var>,
<strong>mach_msg_type_name_t</strong> <var>receive_port_type</var>,
<strong>int</strong> <var>priority</var>,
<strong>filter_array_t</strong> <var>filter</var>,
<strong>mach_msg_type_number_t</strong> <var>filter_count</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>device</var>
<dd>
[in device send right]
A device port
<p>
<dt> <var>receive_port</var>
<dd>
[in filter send or receive (to be converted to send) right]
The port to
receive the input data that is selected by the filter.
<p>
<dt> <var>receive_port_type</var>
<dd>
[in scalar]
IPC type of the send right provided to the device; either
<strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,
or <strong>MACH_MSG_TYPE_COPY_SEND</strong>.
<p>
<dt> <var>priority</var>
<dd>
[in scalar]
Used to order multiple receivers in an implementation
dependent way.
<p>
<dt> <var>filter</var>
<dd>
[pointer to in array of <var>filter_t</var>]
The address of an array of filter values.
<p>
<dt> <var>filter_count</var>
<dd>
[in scalar]
The size of the <var>filter</var> array (in 16-bit values).
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>device_set_filter</strong> function provides a means by
which selected data
appearing at a device interface can be selected and routed to
a port. This service is
provided in support of network devices.
<p>
The filter command list consists of an array of up to <strong>NET_MAX_FILTER</strong>
(16-bit) values to be applied to incoming data "messages" to determine if
that data should be given to a particular input filter.
<p>
Each filter command list specifies a sequence of actions which leave a boolean
value on the top of an internal stack. Each 16-bit value of the command list
specifies a data (push) operation (high order <strong>NETF_NBPO</strong>
bits) as well as a binary operator (low order <strong>NETF_NBPA</strong> bits).
<p>
The value to be pushed onto the stack is chosen as follows:
<dl>
<dt> <strong>NETF_PUSHLIT</strong>
<dd>
Use the next 16-bit value of the filter as the value.
<dt> <strong>NETF_PUSHZERO</strong>
<dd>
Use 0 as the value.
<dt> <strong>NETF_PUSHWORD+</strong><var>N</var>
<dd>
Use 16-bit value <var>N</var> of the "data" portion of the message as the value.
<dt> <strong>NETF_PUSHHDR+</strong><var>N</var>
<dd>
Use 16-bit value <var>N</var> of the "header" portion of the message as the value.
<dt> <strong>NETF_PUSHIND</strong>
<dd>
Pops the top 32-bit value from the stack and then uses it to index the
16-bit value of the "data" portion of the message to be used as the
value.
<dt> <strong>NETF_PUSHHDRIND</strong>
<dd>
Pops the top 32-bit value from the stack and then uses it to index the
16-bit value of the "header" portion of the message to be used as the
value.
<dt> <strong>NETF_PUSHSTK+</strong><var>N</var>
<dd>
Use 32-bit value <var>N</var> of the stack (where the top of stack is value 0) as
the value.
<dt> <strong>NETF_NOPUSH</strong>
<dd>
Don't push a value.
</dl>
The unsigned value so chosen is promoted to a 32-bit value before being pushed.
<p>
Once a value is pushed (except for the case of <strong>NETF_NOPUSH</strong>), the top two
32-bit values of the stack are popped and a binary operator applied to them
(with the old top of stack as the second operand). The result
of the operator is
pushed on the stack. These operators are:
<dl>
<dt> <strong>NETF_NOP</strong>
<dd>
Don't pop off any values and do no operation.
<dt> <strong>NETF_EQ</strong>
<dd>
Perform an equal comparison.
<dt> <strong>NETF_LT</strong>
<dd>
Perform a less than comparison.
<dt> <strong>NETF_LE</strong>
<dd>
Perform a less than or equal comparison.
<dt> <strong>NETF_GT</strong>
<dd>
Perform a greater than comparison.
<dt> <strong>NETF_GE</strong>
<dd>
Perform a greater than or equal comparison.
<dt> <strong>NETF_AND</strong>
<dd>
Perform a bit-wise boolean AND operation.
<dt> <strong>NETF_OR</strong>
<dd>
Perform a bit-wise boolean inclusive OR operation.
<dt> <strong>NETF_XOR</strong>
<dd>
Perform a bit-wise boolean exclusive OR operation.
<dt> <strong>NETF_NEQ</strong>
<dd>
Perform a not equal comparison.
<dt> <strong>NETF_LSH</strong>
<dd>
Perform a left shift operation.
<dt> <strong>NETF_RSH</strong>
<dd>
Perform a right shift operation.
<dt> <strong>NETF_ADD</strong>
<dd>
Perform an addition.
<dt> <strong>NETF_SUB</strong>
<dd>
Perform a subtraction.
<dt> <strong>NETF_COR</strong>
<dd>
Perform an equal comparison. If the comparison is <strong>TRUE</strong>, terminate
the filter list. Otherwise, pop the result of the comparison off the stack.
<dt> <strong>NETF_CAND</strong>
<dd>
Perform an equal comparison. If the comparison is <strong>FALSE</strong>, terminate
the filter list. Otherwise, pop the result of the comparison off the stack.
<dt> <strong>NETF_CNOR</strong>
<dd>
Perform a not equal comparison. If the comparison is <strong>FALSE</strong>,
terminate the filter list. Otherwise, pop the result of the
comparison off the
stack.
<dt> <strong>NETF_CNAND</strong>
<dd>
Perform a not equal comparison. If the comparison is <strong>TRUE</strong>, terminate
the filter list. Otherwise, pop the result of the comparison off the stack.
</dl>
The scan of the filter list terminates when the filter list is emptied, or a
<strong>NETF_C</strong> operation terminates the list. At this time, if the final
value of the top of the stack is <strong>TRUE</strong>, then the message is accepted
for the filter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>D_DEVICE_DOWN</strong>
<dd>
Device has been shut down
<p>
<dt> <strong>D_INVALID_OPERATION</strong>
<dd>
No filter port was supplied.
<p>
<dt> <strong>D_NO_SUCH_DEVICE</strong>
<dd>
No device with that name, or the device is not operational.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Currently no references.