Description

This source file is an example of how to do capture to disk via the segment interface using NTAPI. This example shows the possibility of processing multiple streams within multiple threads.

Each thread processes one stream. Within a thread, the first loop waits for a packet corresponding to the time of the last NTPL command execution. The next loop then processes the received segments for a specific stream.

The following NTAPI functions are used:

• NT_Init()
• NT_NetRxOpen()
• NT_NTPL()
• NT_NetRxRead()
• NT_NetRxGet()
  • NT_NET_GET_SEGMENT_PTR()
  • NT_NET_GET_SEGMENT_LENGTH()
  • NT_NET_GET_SEGMENT_TIMESTAMP()
• NT_NetRxRelease()
• NT_NetRxClose()
• NT_Done()
• NT_ExplainError()

Prerequisites

A Napatech capture accelerator is need to run this example. The ntservice.ini must have at least one HostBuffersRx defined. Below is an example of a minimum ini-file. It will create a 32MB RX hostbuffer from NUMA node 0.

Program flow

The following is required to perform capture of segments to disk:

• #include/nt.h - Applications/Tools only need to include nt.h to obtain prototypes, macros etc. from NTAPI.
• NT_Init(NTAPI_VERSION) - Initialize the NTAPI library. NTAPI_VERSION is a define that describes the version of the API described in the header files included by nt.h. NT_Init() will ask the NTAPI library to convert return data to the NTAPI_VERSION if possible. This will ensure that applications can run on NTAPI libraries of newer versions.
• NT_NTPL() - Assign traffic to the stream. A stream does not return data until traffic is assigned to it by a filter. Stream IDs can be shared between other streams.
• NT_NetRxOpen() - Open the stream using a stream ID. The stream ID must match the one used when creating the filter.
• NT_NetRxRead() - Get the file header. A NT file header must be written to the beginning of the file after the last NT_NTPL() call has been made. Set NtNetRx_s.cmd=NT_NETRX_READ_CMD_GET_FILE_HEADER and issue the NT_NetRxRead() call. The fileheader is returned in NtNetRx_s.u.fileheader.data.
• Create the capture file and write NT header. Use the OS specific functions to create a new capture file.
• Optional step. Wait until we start seeing segments that are hit by the NTPL assign command. This is done to avoid getting segments that are not fully classified by the stream. NT_NetRxGet() is called with a timeout of 1000ms and will return NT_STATUS_TIMEOUT in case nothing is received within 1000ms and will return NT_SUCCESS when a segment is returned. Segments with NT_NET_GET_SEGMENTLENGTH()==0 can be returned so it is needed to check for the segment length before using data within the segment. The NT_NET_GET_SEGMENT_TIMESTAMP() macro can still be used on the empty segments. Return values different from that is an indication of an error. Segments that are prior to the expected time are released via NT_NetRxRelease().
• NT_NetRxGet(), write to file and NT_NetRxRelease() - Receive segments, write to disk and release segments. The Segment macros are used to find the segment and length and timestamp of the segment:
  • NT_NET_GET_SEGMENT_PTR() - Get a pointer to the segment.
  • NT_NET_GET_SEGMENT_LENGTH() - Get length of the segment to store.
  • NT_NET_GET_SEGMENT_TIMESTAMP() - The time the segment was delivered.
  • _nt_net_build_pkt_netbuf() and _nt_net_get_next_packet() are used to traverse packets inside a segment. This is usefull if inspection is needed before saving the segment.
• NT_NetRxClose() - Close the stream when terminating. This will close the stream and release the NTPL assignment made on the hostbuffer.
• Close captured file
• NT_Done() - Close down the NTAPI library.

Code