8.2. Packet Capture
8.2.1. emOpenPacketCapture
-
EC_T_DWORD emOpenPacketCapture(EC_T_DWORD dwInstanceID, EC_T_PACKETCAPTURE_PARMS *pParms)
Open packet capture file (PCAP).
Opens a PCAP trace for further processing within the JobTask. No LinkLayer must have been loaded.
- Parameters
dwInstanceID – [in] Instance ID
pParms – [in] Packet capture parameter
- Returns
EC_E_NOERROR on success
EC_E_INVALIDSTATE if Monitor isn’t initialized or link layer loaded
EC_E_INVALIDPARM if parameter file name invalid
EC_E_OPENFAILED if file could not be opened
EC_E_NOMEMORY if not enough memory available
-
struct EC_T_PACKETCAPTURE_PARMS
Public Members
-
EC_T_CHAR szFileName[EC_PACKETCAPTURE_FILE_NAME_SIZE]
[in] File name. Supported formats are *.pcap or *.pcapng
-
EC_T_BOOL bReadMultipleFiles
[in] Read multiple contiguous files. File name format must be “fileName.nnnnn.pcap[ng]”, e.g. wireshark.00000.pcap
-
EC_T_DWORD dwMaxFrameCnt
[in] Creates a new file every time the number of frames written exceeds this limit. Disabled with a value set to 0.
-
EC_T_DWORD dwMaxFileSize
[in] Creates a new file every time the number of bytes written exceeds this limit. Disabled with a value set to 0.
-
EC_T_DWORD dwRingBufferFileCnt
[in] Form a ring buffer of the capture files with the given number of files. Only if EC_T_PACKETCAPTURE_PARMS::dwMaxFrameCnt or EC_T_PACKETCAPTURE_PARMS::dwMaxFileSize are set. Disabled with a value set to 0.
-
EC_T_CHAR szFileName[EC_PACKETCAPTURE_FILE_NAME_SIZE]
Example
EC_T_PACKETCAPTURE_PARMS PacketCaptureParms;
OsMemset(&PacketCaptureParms, dwInstanceId, sizeof(EC_T_PACKETCAPTURE_PARMS));
OsStrcpy(PacketCaptureParms.szFileName, "C:\\ecat.pcap");
dwRes = emOpenPacketCapture(0, &PacketCaptureParms);
if (EC_E_NOERROR != dwRes)
{
EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "Cannot open packet capture: %s (0x%lx))\n",
ecatGetText(dwRes), dwRes));
}
8.2.2. emClosePacketCapture
-
EC_T_DWORD emClosePacketCapture(EC_T_DWORD dwInstanceID)
Close packet capture file (PCAP).
- Parameters
dwInstanceID – [in] Instance ID
- Returns
EC_E_NOERROR on success
EC_E_INVALIDSTATE if Monitor isn’t initialized or link layer loaded
8.2.3. emGetPacketCaptureInfo
-
EC_T_DWORD emGetPacketCaptureInfo(EC_T_DWORD dwInstanceID, EC_T_PACKETCAPTURE_INFO *pInfo)
Get packet capture file processing status information.
- Parameters
dwInstanceID – [in] Instance ID
pInfo – [out] Packet capture info descriptor
- Returns
EC_E_NOERROR on success
EC_E_INVALIDSTATE if Monitor isn’t initialized or link layer loaded
-
struct EC_T_PACKETCAPTURE_INFO
Public Members
-
EC_T_PACKETCAPTURE_STATUS eStatus
[out] Status of packet capture processing
-
EC_T_CHAR szFileName[EC_PACKETCAPTURE_FILE_NAME_SIZE]
[out] File name of current processed capture
-
EC_T_UINT64 qwFrameNumberTotal
[out] Total number of processed frames from all capture files
-
EC_T_UINT64 qwFrameNumberCur
[out] Last processed frame number from the current packet capture file
-
EC_T_UINT64 qwBytesProcessed
[out] Number of processed bytes from the current packet capture file
-
EC_T_UINT64 qwFileSize
[out] File size[bytes] of the current packet capture
-
EC_T_UINT64 qwTimeStamp
[out] Time stamp[ns] of the last processed frame from the current packet capture file
-
EC_T_DWORD dwCyclesProcessed
[out] Number of EtherCAT cycles processed
-
EC_T_PACKETCAPTURE_STATUS eStatus
8.2.4. emStartLivePacketCapture
-
EC_T_DWORD emStartLivePacketCapture(EC_T_DWORD dwInstanceID, EC_T_PACKETCAPTURE_PARMS *pParms)
Start live packet capture (PCAP).
Starts a live recording of the EtherCAT frames in a specified PCAP file.
Note
Only the PCAP file format is currently supported.
- Parameters
dwInstanceID – [in] Instance ID
pParms – [in] Packet capture parameter
- Returns
EC_E_NOERROR on success
EC_E_INVALIDPARM if parameter file name invalid
EC_E_OPENFAILED if file could not be opened
EC_E_NOMEMORY if not enough memory available
8.2.5. emStopLivePacketCapture
-
EC_T_DWORD emStopLivePacketCapture(EC_T_DWORD dwInstanceID)
Stop live packet capture (PCAP).
Stops a previously started live recording of the EtherCAT frames.
- Parameters
dwInstanceID – [in] Instance ID
- Returns
EC_E_NOERROR on success
EC_E_INVALIDSTATE if Monitor isn’t initialized or no recording is in progress
8.2.6. emBacktracePacketCapture
-
EC_T_DWORD emBacktracePacketCapture(EC_T_DWORD dwInstanceID, EC_T_PACKETCAPTURE_PARMS *pParms)
Dump packet capture (PCAP) from backtrace buffer.
Writes a backtrace of the received frames in a specified PCAP file. The number of frames in the backtrace buffer is parameterized via EC_T_MONITOR_INIT_PARMS::dwBacktraceFrames.
Note
Only the PCAP file format is currently supported.
- Parameters
dwInstanceID – [in] Instance ID
pParms – [in] Packet capture parameter
- Returns
EC_E_NOERROR on success
EC_E_BUSY if another dump is in progress
EC_E_INVALIDSTATE if backtrace buffer is not initialized
EC_E_INVALIDPARM if parameter file name invalid
EC_E_OPENFAILED if file could not be opened
EC_E_NOMEMORY if not enough memory available
See also