PacketFilterExtensionPtr callback function

Article
06/19/2017

The PacketFilterExtensionPtr data type points to a filter-hook callback function. This function processes packets that are passed to it and determines whether to forward or drop the packets or to allow the IP filter driver to further process the packets.

Syntax

typedef PF_FORWARD_ACTION (*PacketFilterExtensionPtr)(
   unsigned char *PacketHeader,
   unsigned char *Packet,
   unsigned int  PacketLength,
   unsigned int  RecvInterfaceIndex,
   unsigned int  SendInterfaceIndex,
   IPAddr        RecvLinkNextHop,
   IPAddr        SendLinkNextHop
);

Parameters

PacketHeader

Pointer to the IP header of the packet. The filter hook can cast the information to which PacketHeader points to an IPHeader structure.

Packet

Pointer to a buffer that contains the information in the packet that the filter hook receives. This buffer does not include the IP header pointed to by PacketHeader.

PacketLength

Size, in bytes, of the information in the IP packet. This size does not include the size of the IP header.

RecvInterfaceIndex

For a received packet, the index number for the network interface controller (NIC) over which the packet arrived. The filter hook uses this index number to identify the particular NIC that received the packet.

For transmitted packets, this parameter is set to INVALID_PF_IF_INDEX and the information in RecvLinkNextHop is meaningless.

SendInterfaceIndex

For a transmitted packet, the index number for the NIC over which the packet will be transmitted. To obtain information about the specified NIC, the filter hook can query the routing table through Simple Network Management Protocol (SNMP).

For received packets, this parameter is set to INVALID_PF_IF_INDEX and the information in SendLinkNextHop is meaningless.

RecvLinkNextHop

IP address for the NIC that received the packet if the NIC is a point to multiple-point interface; otherwise this parameter is set to ZERO_PF_IP_ADDR.

SendLinkNextHop

IP address for the NIC that will transmit the packet if the NIC is a point-to-multiple-point interface; otherwise this parameter is set to ZERO_PF_IP_ADDR.

Return value

Returns one of the following values from the PF_FORWARD_ACTION enumeration:

Return code	Description
PF_FORWARD	Specifies that the IP filter driver immediately return the forward response to the IP stack. IP forwards the packet up the stack for a local packet or routes the packet if the packet's destination is another computer and routing is enabled.
PF_DROP	Specifies that the IP filter driver immediately return the drop response to the IP stack. IP should drop the packet.
PF_PASS	Specifies that the IP filter driver process the packet and return the resulting response to the IP stack. The filter hook returns the pass response if it is determined that it should not process the packet.

Remarks

If the filter hook returns the pass response, the IP filter driver processes the packet. In this case, a user-mode application can control packet filtering through the Packet Filtering API (iphlpapi.lib). This API can be used to create and manage input and output filters for IP packets. Each NIC can have one or more filters associated with it. Filters can include source and destination addresses, address mask and port, and protocol identifier. For more information about this API, refer to the Microsoft Windows SDK.

Note that on Windows Server 2003 and earlier a filter-hook callback function might incompletely receive packets that are sent or received over the network.

The IP filter driver can pass IP header information for a packet in an IPHeader structure. The following section describes IPHeader.

IPHeader

The structure of information to which the PacketHeaderparameter points is typically defined as an IPHeader structure. IPHeader provides details about the packet. IPHeader is defined as follows:


typedef struct IPHeader { UCHAR iph_verlen; UCHAR iph_tos; USHORT iph_length;
        USHORT iph_id; USHORT iph_offset; UCHAR iph_ttl; UCHAR iph_protocol; USHORT iph_xsum; ULONG iph_src;
        ULONG iph_dest; } IPHeader;

The members of this structure contain the following information:

iph_verlen

Specifies the version and length for the packet.

iph_tos

Specifies the type of service for the packet.

iph_length

Size, in bytes, of the packet.

iph_id

Specifies the identity of the packet.

iph_offset

Specifies flags and fragment offset for the packet.

iph_ttl

Specifies the time to live (TTL) for the packet. TTL is a value in the range of zero through 255 that defines the scope within which packets should be sent over a network using IP. The scope is defined in terms of how local or remote a packet's destination is. Each router decrements the TTL by one. When the TTL reaches a predefined lower limit, the router throws the packet away.

iph_protocol

Specifies the protocol for the packet.

iph_xsum

Specifies the header checksum for the packet.

iph_src

Specifies the IP address of a computer that is the source for the packet.

iph_dest

Specifies the IP address of a computer that is the destination for the packet.

Requirements

Target platform	Desktop
Header	Pfhook.h (include Pfhook.h)