Using API

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

The API library has two interfaces for use from C++ and C code, selected by defining the symbol _C_API. It is possible to link with the API code statically or use it as a DLL. The corresponding project configurations are described in the Configurations section. Use the DLL with the C interface in Delphi, CBuilder and other environments that support linking with DLLs. Use the nfapinet wrapper over the 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 report the transmitted data for all TCP connections and UDP sockets.

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

Only one process can use the driver API at the same time. It is possible to register additional instances of the driver with different names in case 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 a pointer to an object of a class derived from NF_EventHandler.

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

  • Handle API notifications in the overridden NF_EventHandler methods. The library calls these methods from a separate thread, so synchronization is required in case the same data are simultaneously accessed from other threads. It is possible to save copies of the indicated data buffers and send the filtered data back to the 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 the 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 in 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 the NFAPI class to filter the network data.