Function rcl_take_serialized_message

Function Documentation

rcl_ret_t rcl_take_serialized_message(const rcl_subscription_t *subscription, rcl_serialized_message_t *serialized_message, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation)

Take a serialized raw message from a topic using a rcl subscription.

In contrast to rcl_take(), this function stores the taken message in its raw binary representation. It is the job of the caller to ensure that the type associate with the subscription matches, and can optionally be deserialized into its ROS message via, the correct type support. If the serialized_message parameter contains enough preallocated memory, the incoming message can be taken without any additional memory allocation. If not, the function will dynamically allocate enough memory for the message. Passing a different type to rcl_take produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

Apart from the differences above, this function behaves like rcl_take().

Attribute

Adherence

Allocates Memory

Maybe [1]

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

[1] only if storage in the serialized_message is insufficient

Parameters:

  • subscription – [in] the handle to the subscription from which to take

  • serialized_message – [inout] pointer to a (pre-allocated) serialized message.

  • message_info – [out] rmw struct which contains meta-data for the message

  • allocation – [in] structure pointer used for memory preallocation (may be NULL)

Returns:

RCL_RET_OK if the message was published, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.