PacketFilterExtensionPtr callback function
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) |
See also
IOCTL_PF_SET_EXTENSION_POINTER