Function rmw_qos_profile_check_compatible

Function Documentation

rmw_ret_t rmw_qos_profile_check_compatible(const rmw_qos_profile_t publisher_profile, const rmw_qos_profile_t subscription_profile, rmw_qos_compatibility_type_t *compatibility, char *reason, size_t reason_size)

Check if two QoS profiles are compatible.

Two QoS profiles are compatible if a publisher and subcription using the QoS policies can communicate with each other.

If any of the profile policies has the value “system default” or “unknown”, then it may not be possible to determine the compatibilty. In this case, the output parameter compatibility is set to RMW_QOS_COMPATIBILITY_WARNING and reason is populated.

If there is a compatibility warning or error, and a buffer is provided for reason, then an explanation of all warnings and errors will be populated into the buffer, separated by semi-colons (;). Errors will appear before warnings in the string buffer. If the provided buffer is not large enough, this function will still write to the buffer, up to the reason_size number of characters. Therefore, it is possible that not all errors and warnings are communicated if the buffer size limit is reached. A buffer size of 2048 should be more than enough to capture all possible errors and warnings.

Attribute

Adherence

Allocates Memory

No

Thread-Safe

Yes

Uses Atomics

No

Lock-Free

Yes

Parameters:

  • publisher_profile – [in] The QoS profile used for a publisher.

  • subscription_profile – [in] The QoS profile used for a subscription.

  • compatibility – [out] RMW_QOS_COMPATIBILITY_OK if the QoS profiles are compatible, or RMW_QOS_COMPATIBILITY_WARNING if the QoS profiles might be compatible, or RMW_QOS_COMPATIBILITY_ERROR if the QoS profiles are not compatible.

  • reason – [out] A detailed reason for a QoS incompatibility or potential incompatibility. Must be pre-allocated by the caller. This parameter is optional and may be set to NULL if the reason information is not desired.

  • reason_size – [in] Size of the string buffer reason, if one is provided. If reason is nullptr, then this parameter must be zero.

Returns:

RMW_RET_OK if the check was successful, or

Returns:

RMW_RET_INVALID_ARGUMENT if compatibility is nullptr, or

Returns:

RMW_RET_INVALID_ARGUMENT if reason is NULL and reason_size is not zero, or

Returns:

RMW_RET_ERROR if there is an unexpected error.