RTI Connext C API Version 7.3.0

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

Data Structures

struct  NDDS_Utility_NetworkCaptureParams_t
 Input parameters for starting network capture. 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...
 

Functions

DDS_Boolean NDDS_Utility_enable_network_capture (void)
 Enable Network Capture. More...
 
DDS_Boolean NDDS_Utility_disable_network_capture (void)
 Disable Network Capture. More...
 
DDS_Boolean NDDS_Utility_set_default_network_capture_params (const NDDS_Utility_NetworkCaptureParams_t *params)
 Set the default Network Capture parameters. More...
 
DDS_Boolean NDDS_Utility_start_network_capture (const char *filename)
 Start capturing traffic for all DomainParticipants, with the default parameters. More...
 
DDS_Boolean NDDS_Utility_start_network_capture_for_participant (DDS_DomainParticipant *participant, const char *filename)
 Start capturing traffic for a DomainParticipant, with the default parameters. More...
 
DDS_Boolean NDDS_Utility_start_network_capture_w_params (const char *filename, const NDDS_Utility_NetworkCaptureParams_t *params)
 Start capturing traffic for all DomainParticipants, with the provided parameters. More...
 
DDS_Boolean NDDS_Utility_start_network_capture_w_params_for_participant (DDS_DomainParticipant *participant, const char *filename, const NDDS_Utility_NetworkCaptureParams_t *params)
 Start capturing traffic for a DomainParticipant, with the provided parameters. More...
 
DDS_Boolean NDDS_Utility_stop_network_capture (void)
 Stop capturing traffic for all participants. More...
 
DDS_Boolean NDDS_Utility_stop_network_capture_for_participant (DDS_DomainParticipant *participant)
 Stop capturing traffic for a DomainParticipant. More...
 
DDS_Boolean NDDS_Utility_pause_network_capture (void)
 Pause capturing traffic for all DomainParticipants. More...
 
DDS_Boolean NDDS_Utility_pause_network_capture_for_participant (DDS_DomainParticipant *participant)
 Pause capturing traffic for a DomainParticipant. More...
 
DDS_Boolean NDDS_Utility_resume_network_capture (void)
 Resume capturing traffic for all DomainParticipants. More...
 
DDS_Boolean NDDS_Utility_resume_network_capture_for_participant (DDS_DomainParticipant *participant)
 Resume capturing traffic for a DomainParticipant. 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 NDDS_Utility_enable_network_capture must be invoked before creating any DomainParticipant. Similarly, NDDS_Utility_disable_network_capture 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_IN).

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.

Function Documentation

◆ NDDS_Utility_enable_network_capture()

DDS_Boolean NDDS_Utility_enable_network_capture ( void  )

Enable Network Capture.

This function must be called before any other Network Capture function. It must also be called before creating the participants for which we want to capture traffic.

Use this function only for debugging purposes, since it may introduce a significant performance impact.

Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
MT Safety:
UNSAFE. It is not safe to call this function while another thread may be simultaneously calling another Network Caputre related function, including this one.
MT Safety:
UNSAFE. In VxWorks, it is unsafe to call this function while another thread may be simulatenously calling DDS_DomainParticipantFactory_get_instance, DDS_DomainParticipantFactory_finalize_instance, DDS_TypeCodeFactory_get_instance, DDS_TypeCodeFactory_finalize_instance, NDDS_Utility_enable_network_capture, or NDDS_Utility_disable_network_capture.
See also
NDDS_Utility_disable_network_capture

◆ NDDS_Utility_disable_network_capture()

DDS_Boolean NDDS_Utility_disable_network_capture ( void  )

Disable Network Capture.

This function must be the last Network Capture function to be called. It must also be called after deleting the participants for which we captured traffic. Disabling Network Capture without stopping it first is not ok!

Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
MT Safety:
UNSAFE. It is not safe to call this function while another thread may be simultaneously calling another Network Capture related function, including this one.
MT Safety:
UNSAFE. In VxWorks, it is unsafe to call this function while another thread may be simulatenously calling DDS_DomainParticipantFactory_get_instance, DDS_DomainParticipantFactory_finalize_instance, DDS_TypeCodeFactory_get_instance, DDS_TypeCodeFactory_finalize_instance, NDDS_Utility_enable_network_capture, or NDDS_Utility_disable_network_capture.
See also
NDDS_Utility_enable_network_capture

◆ NDDS_Utility_set_default_network_capture_params()

DDS_Boolean NDDS_Utility_set_default_network_capture_params ( const NDDS_Utility_NetworkCaptureParams_t params)

Set the default Network Capture parameters.

The default parameters are used when Network Capture is started without parameters, i.e., NDDS_Utility_start_network_capture.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
params<<in>>. Configuration parameters that we want to set as defaults.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_start_network_capture
NDDS_Utility_start_network_capture_for_participant

◆ NDDS_Utility_start_network_capture()

DDS_Boolean NDDS_Utility_start_network_capture ( const char *  filename)

Start capturing traffic for all DomainParticipants, with the default parameters.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, the "_GUID-" string followed by the decimal representation of bytes 8-11 of the DomainParticipant's GUID, and the file extension (".pcap").

Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_stop_network_capture
NDDS_Utility_start_network_capture_for_participant

◆ NDDS_Utility_start_network_capture_for_participant()

DDS_Boolean NDDS_Utility_start_network_capture_for_participant ( DDS_DomainParticipant participant,
const char *  filename 
)

Start capturing traffic for a DomainParticipant, with the default parameters.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
participant<<in>>. DomainParticipant for which we want to capture traffic.
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, and the file extension (".pcap").

Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_stop_network_capture_for_participant
NDDS_Utility_start_network_capture_w_params_for_participant
NDDS_Utility_enable_network_capture

◆ NDDS_Utility_start_network_capture_w_params()

DDS_Boolean NDDS_Utility_start_network_capture_w_params ( const char *  filename,
const NDDS_Utility_NetworkCaptureParams_t params 
)

Start capturing traffic for all DomainParticipants, with the provided parameters.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Perfoms the same function as NDDS_Utility_start_network_capture except that it uses the provided parameters, instead of the default ones.

Parameters
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, the "_GUID-" string followed by the decimal representation of bytes 8-11 of the DomainParticipant's GUID, and the file extension (".pcap").

Parameters
params<<in>>. Configuration parameters for the capture.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_stop_network_capture
NDDS_Utility_start_network_capture_w_params_for_participant

◆ NDDS_Utility_start_network_capture_w_params_for_participant()

DDS_Boolean NDDS_Utility_start_network_capture_w_params_for_participant ( DDS_DomainParticipant participant,
const char *  filename,
const NDDS_Utility_NetworkCaptureParams_t params 
)

Start capturing traffic for a DomainParticipant, with the provided parameters.

Precondition
This function requires enabling first Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
participant<<in>>. DomainParticipant for which we want to capture traffic.
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, and the file extension (".pcap").

Parameters
params<<in>>. Parameters for configuring the capture.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_stop_network_capture_for_participant
NDDS_Utility_start_network_capture_for_participant

◆ NDDS_Utility_stop_network_capture()

DDS_Boolean NDDS_Utility_stop_network_capture ( void  )

Stop capturing traffic for all participants.

Precondition
This function requires enabling first Network Capture. See NDDS_Utility_enable_network_capture.

This function can (and must) be called after NDDS_Utility_start_network_capture, not NDDS_Utility_start_network_capture_for_participant. That is, if we start capturing traffic globally (for all DomainParticipants), we must stop capturing traffic also globally. It is not possible to start capturing traffic for a participant but stop it globally.

It is possible to start capturing globally and then stop capturing for a participant, as long as we eventually stop capturing traffic globally.

We must stop capturing for a participant before deleting it.

Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_start_network_capture
NDDS_Utility_stop_network_capture_for_participant

◆ NDDS_Utility_stop_network_capture_for_participant()

DDS_Boolean NDDS_Utility_stop_network_capture_for_participant ( DDS_DomainParticipant participant)

Stop capturing traffic for a DomainParticipant.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
participant<<in>>. DomainParticipant for which we want to stop capturing traffic.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_start_network_capture_for_participant
NDDS_Utility_stop_network_capture

◆ NDDS_Utility_pause_network_capture()

DDS_Boolean NDDS_Utility_pause_network_capture ( void  )

Pause capturing traffic for all DomainParticipants.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_resume_network_capture
NDDS_Utility_pause_network_capture_for_participant

◆ NDDS_Utility_pause_network_capture_for_participant()

DDS_Boolean NDDS_Utility_pause_network_capture_for_participant ( DDS_DomainParticipant participant)

Pause capturing traffic for a DomainParticipant.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
participant<<in>>. DomainParticipant for which we want to pause capturing traffic.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_resume_network_capture_for_participant
NDDS_Utility_pause_network_capture

◆ NDDS_Utility_resume_network_capture()

DDS_Boolean NDDS_Utility_resume_network_capture ( void  )

Resume capturing traffic for all DomainParticipants.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_pause_network_capture
NDDS_Utility_resume_network_capture_for_participant

◆ NDDS_Utility_resume_network_capture_for_participant()

DDS_Boolean NDDS_Utility_resume_network_capture_for_participant ( DDS_DomainParticipant participant)

Resume capturing traffic for a DomainParticipant.

Precondition
This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.
Parameters
participant<<in>>. DomainParticipant for which we want to resume capturing traffic.
Returns
DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE
See also
NDDS_Utility_pause_network_capture_for_participant
NDDS_Utility_resume_network_capture

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 function:

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.