Function rmw_subscription_set_on_new_message_callback

Function Documentation

rmw_ret_t rmw_subscription_set_on_new_message_callback(rmw_subscription_t *subscription, rmw_event_callback_t callback, const void *user_data)

Set the on new message callback function for the subscription.

This API sets the callback function to be called whenever the subscription is notified about a new message.

This callback is called for each new message received by the subscription. If messages arrive before the callback is registered, the number_of_events argument given to the callback may be > 1.

The callback may be called from a thread that the rmw implementation created, rather than a thread owned by the user, i.e. some thread other than user owned threads calling rmw functions such as rmw_wait() or rmw_publish().

This function is thread-safe. This is required of the rmw implementation because the callback may be called from any middleware thread, and this function could be called by the user at any time.

Parameters:

  • subscription – [in] The subscription on which to set the callback

  • callback – [in] The callback to be called when new messages arrive, can be NULL to clear the registered callback

  • user_data – [in] Given to the callback when called later, may be NULL

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_INVALID_ARGUMENT if subscription is NULL, or

Returns:

RMW_RET_UNSUPPORTED if the API is not implemented in the dds implementation