RTI Connext Traditional C++ API Version 7.3.0

Save network traffic into a capture file for further analysis. More...

Classes

struct  NDDS_Utility_NetworkCaptureParams_t
 Input parameters for starting network capture. More...
 
class  NDDSUtilityNetworkCapture
 Network Capture APIs. More...
 

Macros

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_DEFAULT
 Default mask for NDDS_Utility_NetworkCaptureContentKind: do not remove any content. More...
 
#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE
 The RTPS frames in the capture file will be saved as they are. More...
 
#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_ALL
 The RTPS frames in the capture file will not include user data (either plain or encrypted). More...
 
#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_DEFAULT
 Default mask for NDDS_Utility_NetworkCaptureTrafficKindMask. More...
 
#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE
 Do not capture any traffic. More...
 
#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL
 Capture all traffic (both inbound and outbound). More...
 

Typedefs

typedef DDS_Long NDDS_Utility_NetworkCaptureContentKindMask
 Mask that indicates a combination of content types. More...
 
typedef DDS_Long NDDS_Utility_NetworkCaptureTrafficKindMask
 Mask that indicates the traffic direction to capture. More...
 
typedef struct NDDS_Utility_NetworkCaptureParams_t NDDS_Utility_NetworkCaptureParams_t
 Input parameters for starting network capture. More...
 

Enumerations

enum  NDDS_Utility_NetworkCaptureContentKind {
  NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_USER_SERIALIZED_DATA ,
  NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_ENCRYPTED_DATA
}
 Bitmap used to specify a content type, i.e., a part of the RTPS frame. More...
 
enum  NDDS_Utility_NetworkCaptureTrafficKind {
  NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT ,
  NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_IN
}
 Bitmap used to specify whether we want to capture inbound or outbound traffic. More...
 

Variables

const NDDS_Utility_NetworkCaptureParams_t NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT
 Default parameters used in Network Capture. More...
 

Detailed Description

Save network traffic into a capture file for further analysis.

RTI Connext allows you to capture the network traffic that one or more DomainParticipants send or receive. This feature can be used to analyze and debug communication problems between your DDS applications. When network capture is enabled, each DomainParticipant will generate a pcap-based file that can then be opened by a packet analyzer like Wireshark, provided the right dissectors are installed.

To some extent, network capture can be used as an alternative to existing pcap-based network capture software (such as Wireshark). This will be the case when you are only interested in analyzing the traffic a DomainParticipant sends/receives. In this scenario, network capture will actually have some advantages over using more general pcap-based network capture applications: RTI's network capture includes additional information such as security-related data; it also removes information that is not needed, such as user data, when you want to reduce the capture size. That said, RTI's network capture is not a replacement for other pcap-based network capture applications: it only captures the traffic exchanged by the DomainParticipants, but it does not capture any other traffic exchanged through the system network interfaces.

To capture network traffic NDDSUtilityNetworkCapture::enable must be invoked before creating any DomainParticipant. Similarly, NDDSUtilityNetworkCapture::disable must be called after deleting all participants. In between these calls, you may start, stop, pause or resume capturing traffic for one or all participants.

Capturing

Shared Memory Traffic

Every RTPS frame in network capture has a source and a destination associated with it. In the case of shared memory traffic, a process identifier and a port determine the source and destination endpoints.

Access to the process identifier (PID) of the source for inbound traffic requires changes in the shared memory segments. These changes would break shared memory compatibility with previous versions of RTI Connext. For this reason, by default, network capture will not populate the value of the source PID for inbound shared memory traffic.

If interoperability with previous versions of RTI Connext is not necessary, you can generate capture files containing the source PID for inbound traffic. To do so, configure the value of the 'dds.transport.minimum_compatibility_version' property to 6.1.0. (See DDS_PropertyQosPolicy).

<domain_participant_qos>
<property>
<value>
<element>
<name>dds.transport.minimum_compatibility_version</name>
<value>6.1.0</value>
<propagate>false</propagate>
</element>
</value>
</property>
</domain_participant_qos>

This property is never propagated, so it must be consistently configured throughout the whole system.

Note: Changing the value of this property affects the type of shared memory segments that RTI Connext uses. For that reason, you may see the following warning, resulting from leftover shared memory segments:

[0xC733A001,0xB248F671,0xAEC4A0C1:0x000001C1{Domain=200}|CREATE DP|ENABLE] NDDS_Transport_Shmem_is_segment_compatible:incompatible shared memory protocol detected.
Current version 4.0 not compatible with 2.0.

The leftover shared memory segments can be removed using the ipcrm command. See https://community.rti.com/kb/what-are-possible-solutions-common-shared-memory-issues for more information.

Macro Definition Documentation

◆ NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_DEFAULT

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_DEFAULT

Default mask for NDDS_Utility_NetworkCaptureContentKind: do not remove any content.

It is equivalent to NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE.

[default] Do not remove any content.

◆ NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE

The RTPS frames in the capture file will be saved as they are.

◆ NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_ALL

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_ALL

The RTPS frames in the capture file will not include user data (either plain or encrypted).

Its value is the result of setting the bits for removing user data and removing encrypted data: (NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_USER_SERIALIZED_DATA) | NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_ENCRYPTED_DATA)

◆ NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_DEFAULT

#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_DEFAULT

Default mask for NDDS_Utility_NetworkCaptureTrafficKindMask.

It is equivalent to NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL.

[default] Capture all traffic: inbound and outbound.

◆ NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE

#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE

Do not capture any traffic.

◆ NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL

#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL

Capture all traffic (both inbound and outbound).

The value is equal to setting both the input and output bits of the mask: (NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT | NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT).

Typedef Documentation

◆ NDDS_Utility_NetworkCaptureContentKindMask

Mask that indicates a combination of content types.

The masks are based on a combination (or only one) of the NDDS_Utility_NetworkCaptureContentKind bitmaps.

See also
NDDS_Utility_NetworkCaptureContentKind

◆ NDDS_Utility_NetworkCaptureTrafficKindMask

Mask that indicates the traffic direction to capture.

The masks are based on a combination (or only one) of the NDDS_Utility_NetworkCaptureTrafficKind bitmaps.

See also
NDDS_Utility_NetworkCaptureTrafficKind

◆ NDDS_Utility_NetworkCaptureParams_t

Input parameters for starting network capture.

Enumeration Type Documentation

◆ NDDS_Utility_NetworkCaptureContentKind

Bitmap used to specify a content type, i.e., a part of the RTPS frame.

Several values can be combined. Read NDDS_Utility_NetworkCaptureContentKindMask for typical combinations.

Enumerator
NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_USER_SERIALIZED_DATA 

The serialized data coming from a user.

NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_ENCRYPTED_DATA 

The encrypted user data.

◆ NDDS_Utility_NetworkCaptureTrafficKind

Bitmap used to specify whether we want to capture inbound or outbound traffic.

Several values can be combined. Read NDDS_Utility_NetworkCaptureTrafficKindMask for typical combinations.

Enumerator
NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT 

Do not capture outbound traffic.

NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_IN 

Do not capture inbound traffic.

Variable Documentation

◆ NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT

const NDDS_Utility_NetworkCaptureParams_t NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT
extern

Default parameters used in Network Capture.

The default parameters can be used as initilizers to ensure that new objects do not have uninitialized contents.

Initialization of a NDDS_Utility_NetworkCaptureParams_t type can be done either by assigning to the default parameters:

const NDDS_Utility_NetworkCaptureParams_t NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT
Default parameters used in Network Capture.
Input parameters for starting network capture.
Definition: ndds_utility_c.ifc:272

Or equivalently, by using its initializer method:

NDDS_Utility_NetworkCaptureParams_t_initialize(&params);

In either case, do not forget to finalize the parameters when you don't need them any more:

NDDS_Utility_NetworkCaptureParams_t_finalize(&params);

The values that are used by default for the parameters can be found in the description of each of the members in NDDS_Utility_NetworkCaptureParams_t.