Packet Sniffer SDK DLL Edition

HNFileAdapter :: Methods :: FAdpCreateFile

Creates a CAP file.

Syntax:

DWORD __stdcall FAdpCreateFile(HANDLE hFAdp, LPCTSTR FileName);

Parameters:

hFAdp

[in] HNFileAdapter object handle.

FileName

[in] A path to a file.

Return values:

HNERR_OK	CAP file opening has been completed successfully.
HNERR_INCOMPATIBLE_MODE	Incompatible mode of HNFileAdapter. Occurs when HNFileAdapter.AutoMode was set [Get/Set]), but HNQueue object was not predetermined (see HNFileAdapter.Queue [Get/Set]).
HNERR_BAD_MEDIUM_TYPE	Impossible adapter type is set for format of packets to be dumped to the CAP file.
HNERR_MEM_ALLOC_ERROR	The memory for the traffic processing is not allocated. This can happen either because of the insufficient operating system resources or in case of HNQueue component using (see QueAllocItems).
HNERR_UNKNOWN_FILE_FORMAT	Unknown CAP file format is set (see HNFileAdapter.CapFormat [Get/Set]).
HNERR_OPEN_FILE	CAP file opening error.
HNERR_ADAPTER_THREAD_ERR	Packet Sniffer SDK internal thread creation error.
HNERR_INVALID_HANDLE	hFAdp parameter is not the HNFileAdapter object handle.

Description:

Use FAdpCreateFile to create a new CAP file. If the function succeeds, you can begin to dump network traffic to the CAP file using FAdpSyncSend and FAdpSyncSendEx functions.

When HNFileAdapter object works in AutoMode using of FAdpSyncSend and FAdpSyncSendEx functions is impossible.

If HNFileAdapter.Queue property [Get/Set] was set before the network adapter opening, and HNFileAdapter object Automode was set (see HNFileAdapter.AutoMode [Get/ Set]), then the traffic will be processed in the HNFileAdapter internal thread context together with HNQueue component. In this mode you also may use HNFileAdapter.SizeLimit property [Get/Set] to set limitation for CAP file size.

On executing FAdpCreateFile function HNFileAdapter component attempts to close the CAP file which was opened earlier. So, one instance of HNFileAdapter object can open only one CAP file.

If you need to open/create several CAP files simultaneously, you may create several HNFileAdapter objects with appropriate settings.

To read from existing CAP file please use FAdpOpenFile function.

Example of dumping packets to a CAP file in HNFileAdpater AutoMode:

// OnFileClose event handler
void __stdcall OnFileClose(DWORD_PTR Param, DWORD_PTR ThParam, DWORD Result)
{
    if (Result == HNERR_FILE_SIZE_LIMIT)
    {
      ...
    }
}
...
// Create HNAdapter object
HANDLE hAdp = AdpCreate(); 
// create HNQueue object
HANDLE hQue = QueCreate(); 
// Create HNFileAdapter object
HANDLE hFАdp = FAdpCreate(); 
...
// Set HNQueue object for HNAdapter and HNFileAdapter
AdpSetReceiveQueue(hAdp, hQue);
FAdpSetQueue(hFAdp, hQue);

// HNFileAdapter additional settings
FAdpSetAutoMode(hFAdp, TRUE);
FAdpSetSizeLimit(hFAdp, 1000000);
FAdpSetOnFileClose(hFAdp, OnFileClose, 0);

// Create CAP file
DWORD Res = FAdpCreateFile(hFAdp, "packets.cap");
...
// Start queue internal thread
Res = QueStart(hQue);
...
// Open network adapter
Res = AdpOpenAdapter(hAdp);
...