RTI Connext C API
Version 6.1.2
|
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... | |
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.
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).
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:
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.
#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.
#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE |
The RTPS frames in the capture file will be saved as they are.
#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)
#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.
#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE |
Do not capture any traffic.
#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).
Mask that indicates a combination of content types.
The masks are based on a combination (or only one) of the NDDS_Utility_NetworkCaptureContentKind bitmaps.
Mask that indicates the traffic direction to capture.
The masks are based on a combination (or only one) of the NDDS_Utility_NetworkCaptureTrafficKind bitmaps.
Input parameters for starting network capture.
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. |
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. |
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.
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!
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.
params | <<in>>. Configuration parameters that we want to set as defaults. |
DDS_Boolean NDDS_Utility_start_network_capture | ( | const char * | filename | ) |
Start capturing traffic for all DomainParticipants, with the default 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"
).
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.
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"
).
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.
Perfoms the same function as NDDS_Utility_start_network_capture except that it uses the provided parameters, instead of the default ones.
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"
).
params | <<in>>. Configuration parameters for the capture. |
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.
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"
).
params | <<in>>. Parameters for configuring the capture. |
DDS_Boolean NDDS_Utility_stop_network_capture | ( | void | ) |
Stop capturing traffic for all participants.
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.
DDS_Boolean NDDS_Utility_stop_network_capture_for_participant | ( | DDS_DomainParticipant * | participant | ) |
Stop capturing traffic for a DomainParticipant.
participant | <<in>>. DomainParticipant for which we want to stop capturing traffic. |
DDS_Boolean NDDS_Utility_pause_network_capture | ( | void | ) |
Pause capturing traffic for all DomainParticipants.
DDS_Boolean NDDS_Utility_pause_network_capture_for_participant | ( | DDS_DomainParticipant * | participant | ) |
Pause capturing traffic for a DomainParticipant.
participant | <<in>>. DomainParticipant for which we want to pause capturing traffic. |
DDS_Boolean NDDS_Utility_resume_network_capture | ( | void | ) |
Resume capturing traffic for all DomainParticipants.
DDS_Boolean NDDS_Utility_resume_network_capture_for_participant | ( | DDS_DomainParticipant * | participant | ) |
Resume capturing traffic for a DomainParticipant.
participant | <<in>>. DomainParticipant for which we want to resume capturing traffic. |
const NDDS_Utility_NetworkCaptureParams_t NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT |
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:
Or equivalently, by using its initializer function:
In either case, do not forget to finalize the parameters when you don't need them any more:
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.