Using API

The network hooking driver must be installed on the target system as described in Installation topic.

The API library has two interfaces for use from C++ and C code, switched by defining the symbol _C_API. It is possible to link with API code statically or use it as a DLL. The corresponding project configurations are described in Configurations section. Use the DLL with C interface in Delphi, CBuilder and other environments that support linking with DLLs. Use nfapinet wrapper over C++ API from .NET code.

By default the driver allows all network activity and bypasses the data packets without filtering. It notifies the API about creating and closing TCP connections and UDP sockets, but doesn’t allow filtering the transmitted data. The client application must create one or more rules using the driver API to specify which network activity must be filtered. For example it is possible to create a rule with all zeros except filteringFlag set to NF_FILTER, and the driver will indicate the transmitted data for all TCP connections and UDP sockets.

The driver breaks all filtered TCP connections and returns back to “bypass all” mode after the expected or unexpected closure of the attached process.

Only one process can use the driver API at a time. It is possible to register additional instances of the driver with different names if several processes must be able to filter the network activity on the same system. See the Installation section for details.

Usage scenarios

C++

  • Implement the methods of NF_EventHandler by defining a class derived from this interface.

  • Initialize the API with a call to nf_init(), specifying the driver name and the pointer to an object of class derived from NF_EventHandler.

  • Add the filtering rules using nf_addRule(), nf_addRuleEx(), nf_setRules(), nf_setRulesEx().

  • Handle API notifications in overridden NF_EventHandler methods. The library calls these methods from a separate thread, so synchronization is required if the same data are simultaneously accessed from other threads. It is possible to save copies of indicated data buffers and send the filtered data back to destination from any thread later.

  • To remove the rules from the driver and disable filtering of new connections, call nf_deleteRules(). The library continues indicating events for active TCP connections in this case until they close, because the filtering flag is assigned when a connection is being established, and remains active during the connection lifetime.

  • Call nf_free() to detach from driver.

C

  • Define the symbol _C_API before including nfapi.h and link with the corresponding build of nfapi.lib. It is also possible to load the library nfapi.dll dynamically and use the exported functions via GetProcAddress.

  • For C projects, NF_EventHandler is defined as a structure with pointers to event handler functions.

Everything else is the same as for C++.

Delphi, CBuilder

  • Include NetFilter2API.pas from the samples\nfsdk\Delphi\include folder.

  • Fill the structure NF_EventHandler with pointers to event handler functions and pass the pointer to nf_init().

Everything else is the same as for C++.

C#

  • Add a reference to samples\nfsdk\C#\include\nfapinet.cs. It is a managed wrapper over the C API that exports a managed analogue of the nfapi interface.

  • Implement the NF_EventHandler interface and use the static functions of NFAPI class to filter the network data.