## device_set_filter

Function - Name an input filter for a device.

### SYNOPSIS

    #include< device/device.h>
    #include< device/net_status.h>

    kern_return_t   device_set_filter
                    (mach_port_t                             device,
                     mach_port_t                       receive_port,
                     mach_msg_type_name_t         receive_port_type,
                     int                                   priority,
                     filter_array_t                          filter,
                     mach_msg_type_number_t             filter_count);

### PARAMETERS

device
  [in device send right] A device port

receive_port
  [in filter send or receive (to be converted to send) right] The port to receive the input data that is selected by the filter.

receive_port_type
  [in scalar] IPC type of the send right provided to the device; either MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND.

priority
  [in scalar] Used to order multiple receivers in an implementation dependent way.

filter
  [pointer to in array of filter_t] The address of an array of filter values.

filter_count
  [in scalar] The size of the filter array (in 16-bit values).

### DESCRIPTION

The device_set_filter 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.

The filter command list consists of an array of up to NET_MAX_FILTER (16-bit) values to be applied to incoming data "messages" to determine if that data should be given to a particular input filter.

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 NETF_NBPO bits) as well as a binary operator (low order NETF_NBPA bits).

The value to be pushed onto the stack is chosen as follows:

NETF_PUSHLIT
  Use the next 16-bit value of the filter as the value.
NETF_PUSHZERO
  Use 0 as the value.
NETF_PUSHWORD+N
  Use 16-bit value N of the "data" portion of the message as the value.
NETF_PUSHHDR+N
  Use 16-bit value N of the "header" portion of the message as the value.
NETF_PUSHIND
  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.
NETF_PUSHHDRIND
  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.
NETF_PUSHSTK+N
  Use 32-bit value N of the stack (where the top of stack is value 0) as the value.
NETF_NOPUSH
  Don't push a value.

The unsigned value so chosen is promoted to a 32-bit value before being pushed.

Once a value is pushed (except for the case of NETF_NOPUSH), 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:

NETF_NOP
  Don't pop off any values and do no operation.
NETF_EQ
  Perform an equal comparison.
NETF_LT
  Perform a less than comparison.
NETF_LE
  Perform a less than or equal comparison.
NETF_GT
  Perform a greater than comparison.
NETF_GE
  Perform a greater than or equal comparison.
NETF_AND
  Perform a bit-wise boolean AND operation.
NETF_OR
  Perform a bit-wise boolean inclusive OR operation.
NETF_XOR
  Perform a bit-wise boolean exclusive OR operation.
NETF_NEQ
  Perform a not equal comparison.
NETF_LSH
  Perform a left shift operation.
NETF_RSH
  Perform a right shift operation.
NETF_ADD
  Perform an addition.
NETF_SUB
  Perform a subtraction.
NETF_COR
  Perform an equal comparison. If the comparison is TRUE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
NETF_CAND
  Perform an equal comparison. If the comparison is FALSE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
NETF_CNOR
  Perform a not equal comparison. If the comparison is FALSE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.
NETF_CNAND
  Perform a not equal comparison. If the comparison is TRUE, terminate the filter list. Otherwise, pop the result of the comparison off the stack.

The scan of the filter list terminates when the filter list is emptied, or a NETF_C operation terminates the list. At this time, if the final value of the top of the stack is TRUE, then the message is accepted for the filter.

### RETURN VALUES

D_DEVICE_DOWN
  Device has been shut down

D_INVALID_OPERATION
  No filter port was supplied.

D_NO_SUCH_DEVICE
  No device with that name, or the device is not operational.

### RELATED INFORMATION

Currently no references.