rmw  master
C API providing a middleware abstraction layer which is used to implement the rest of ROS.
Functions
rmw.h File Reference
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "rcutils/types.h"
#include "rosidl_generator_c/message_type_support_struct.h"
#include "rosidl_generator_c/service_type_support_struct.h"
#include "rmw/init.h"
#include "rmw/macros.h"
#include "rmw/qos_profiles.h"
#include "rmw/types.h"
#include "rmw/visibility_control.h"
Include dependency graph for rmw.h:

Go to the source code of this file.

Functions

const char * rmw_get_implementation_identifier (void)
 
const char * rmw_get_serialization_format (void)
 Get the unique serialization format for this middleware. More...
 
rmw_node_trmw_create_node (rmw_context_t *context, const char *name, const char *namespace_, size_t domain_id, const rmw_node_security_options_t *security_options)
 Create a node and return a handle to that node. More...
 
rmw_ret_t rmw_destroy_node (rmw_node_t *node)
 Finalize a given node handle, reclaim the resources, and deallocate the node handle. More...
 
const rmw_guard_condition_trmw_node_get_graph_guard_condition (const rmw_node_t *node)
 Return a guard condition which is triggered when the ROS graph changes. More...
 
rmw_publisher_trmw_create_publisher (const rmw_node_t *node, const rosidl_message_type_support_t *type_support, const char *topic_name, const rmw_qos_profile_t *qos_policies)
 
rmw_ret_t rmw_destroy_publisher (rmw_node_t *node, rmw_publisher_t *publisher)
 
rmw_ret_t rmw_publish (const rmw_publisher_t *publisher, const void *ros_message)
 
rmw_ret_t rmw_publisher_count_matched_subscriptions (const rmw_publisher_t *publisher, size_t *subscription_count)
 Retrieve the number of matched subscriptions to a publisher. More...
 
rmw_ret_t rmw_publish_serialized_message (const rmw_publisher_t *publisher, const rmw_serialized_message_t *serialized_message)
 Publish an already serialized message. More...
 
rmw_ret_t rmw_serialize (const void *ros_message, const rosidl_message_type_support_t *type_support, rmw_serialized_message_t *serialized_message)
 Serialize a ROS message into a rmw_serialized_message_t. More...
 
rmw_ret_t rmw_deserialize (const rmw_serialized_message_t *serialized_message, const rosidl_message_type_support_t *type_support, void *ros_message)
 Deserialize a ROS message. More...
 
rmw_subscription_trmw_create_subscription (const rmw_node_t *node, const rosidl_message_type_support_t *type_support, const char *topic_name, const rmw_qos_profile_t *qos_policies, bool ignore_local_publications)
 
rmw_ret_t rmw_destroy_subscription (rmw_node_t *node, rmw_subscription_t *subscription)
 
rmw_ret_t rmw_subscription_count_matched_publishers (const rmw_subscription_t *subscription, size_t *publisher_count)
 Retrieve the number of matched publishers to a subscription. More...
 
rmw_ret_t rmw_take (const rmw_subscription_t *subscription, void *ros_message, bool *taken)
 
rmw_ret_t rmw_take_with_info (const rmw_subscription_t *subscription, void *ros_message, bool *taken, rmw_message_info_t *message_info)
 
rmw_ret_t rmw_take_serialized_message (const rmw_subscription_t *subscription, rmw_serialized_message_t *serialized_message, bool *taken)
 Take a message without deserializing it. More...
 
rmw_ret_t rmw_take_serialized_message_with_info (const rmw_subscription_t *subscription, rmw_serialized_message_t *serialized_message, bool *taken, rmw_message_info_t *message_info)
 Take a message without deserializing it and with its additional message information. More...
 
rmw_client_trmw_create_client (const rmw_node_t *node, const rosidl_service_type_support_t *type_support, const char *service_name, const rmw_qos_profile_t *qos_policies)
 
rmw_ret_t rmw_destroy_client (rmw_node_t *node, rmw_client_t *client)
 
rmw_ret_t rmw_send_request (const rmw_client_t *client, const void *ros_request, int64_t *sequence_id)
 
rmw_ret_t rmw_take_response (const rmw_client_t *client, rmw_request_id_t *request_header, void *ros_response, bool *taken)
 
rmw_service_trmw_create_service (const rmw_node_t *node, const rosidl_service_type_support_t *type_support, const char *service_name, const rmw_qos_profile_t *qos_policies)
 
rmw_ret_t rmw_destroy_service (rmw_node_t *node, rmw_service_t *service)
 
rmw_ret_t rmw_take_request (const rmw_service_t *service, rmw_request_id_t *request_header, void *ros_request, bool *taken)
 
rmw_ret_t rmw_send_response (const rmw_service_t *service, rmw_request_id_t *request_header, void *ros_response)
 
rmw_guard_condition_trmw_create_guard_condition (rmw_context_t *context)
 Create a guard condition and return a handle to that guard condition. More...
 
rmw_ret_t rmw_destroy_guard_condition (rmw_guard_condition_t *guard_condition)
 Finalize a given guard condition handle, reclaim the resources, and deallocate the handle. More...
 
rmw_ret_t rmw_trigger_guard_condition (const rmw_guard_condition_t *guard_condition)
 
rmw_wait_set_trmw_create_wait_set (size_t max_conditions)
 Create a wait set to store conditions that the middleware will block on. More...
 
rmw_ret_t rmw_destroy_wait_set (rmw_wait_set_t *wait_set)
 
rmw_ret_t rmw_wait (rmw_subscriptions_t *subscriptions, rmw_guard_conditions_t *guard_conditions, rmw_services_t *services, rmw_clients_t *clients, rmw_wait_set_t *wait_set, const rmw_time_t *wait_timeout)
 Waits on sets of different waitable entities and returns when one is ready. More...
 
rmw_ret_t rmw_get_node_names (const rmw_node_t *node, rcutils_string_array_t *node_names, rcutils_string_array_t *node_namespaces)
 Return a list of node name and namespaces discovered via a node. More...
 
rmw_ret_t rmw_count_publishers (const rmw_node_t *node, const char *topic_name, size_t *count)
 
rmw_ret_t rmw_count_subscribers (const rmw_node_t *node, const char *topic_name, size_t *count)
 
rmw_ret_t rmw_get_gid_for_publisher (const rmw_publisher_t *publisher, rmw_gid_t *gid)
 
rmw_ret_t rmw_compare_gids_equal (const rmw_gid_t *gid1, const rmw_gid_t *gid2, bool *result)
 
rmw_ret_t rmw_service_server_is_available (const rmw_node_t *node, const rmw_client_t *client, bool *is_available)
 Check if a service server is available for the given service client. More...
 
rmw_ret_t rmw_set_log_severity (rmw_log_severity_t severity)
 

Function Documentation

◆ rmw_get_implementation_identifier()

const char* rmw_get_implementation_identifier ( void  )

◆ rmw_get_serialization_format()

const char* rmw_get_serialization_format ( void  )

Get the unique serialization format for this middleware.

Return the format in which binary data is serialized. One middleware can only have one encoding. In contrast to the implementation identifier, the serialization format can be equal between multiple RMW implementations. This means, that the same binary messages can be deserialized by RMW implementations with the same format.

See also
rmw_serialize
rmw_deserialize
Returns
serialization format

◆ rmw_create_node()

rmw_node_t* rmw_create_node ( rmw_context_t context,
const char *  name,
const char *  namespace_,
size_t  domain_id,
const rmw_node_security_options_t security_options 
)

Create a node and return a handle to that node.

This function can fail, and therefore return NULL, if:

  • context, name, namespace_, or security_options is NULL
  • context, security_options is invalid
  • memory allocation fails during node creation
  • an unspecified error occurs

The context must be non-null and valid, i.e. it has been initialized by rmw_init() and has not been finalized by rmw_shutdown().

The name and namespace_ should be valid node name and namespace, and this should be asserted by the caller (e.g. rcl).

The domain ID should be used to physically separate nodes at the communication graph level by the middleware. For RTPS/DDS this maps naturally to their concept of domain id.

The security options should always be non-null and encapsulate the essential security configurations for the node and its entities.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No [1]
Lock-Free No [1]

[1] rmw implementation defined, check the implementation documentation

This should be defined by the rmw implementation.

Parameters
[in]contextinit context that this node should be associated with
[in]namethe node name
[in]namespace_the node namespace
[in]domain_idthe id of the domain that the node should join
[in]security_optionsthe security configurations for the node
Returns
rmw node handle or NULL if there was an error

◆ rmw_destroy_node()

rmw_ret_t rmw_destroy_node ( rmw_node_t node)

Finalize a given node handle, reclaim the resources, and deallocate the node handle.

Parameters
nodethe node handle to be destroyed
Returns
RMW_RET_OK if successful, or
RMW_RET_INVALID_ARGUMENT if node is null, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_node_get_graph_guard_condition()

const rmw_guard_condition_t* rmw_node_get_graph_guard_condition ( const rmw_node_t node)

Return a guard condition which is triggered when the ROS graph changes.

The handle returned is a pointer to an internally held rmw guard condition. This function can fail, and therefore return NULL, if:

  • node is NULL
  • node is invalid

The returned handle is made invalid if the node is destroyed or if rmw_shutdown() is called.

The guard condition will be triggered anytime a change to the ROS graph occurs. A ROS graph change includes things like (but not limited to) a new publisher advertises, a new subscription is created, a new service becomes available, a subscription is canceled, etc.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]nodepointer to the rmw node
Returns
rmw guard condition handle if successful, otherwise NULL

◆ rmw_create_publisher()

rmw_publisher_t* rmw_create_publisher ( const rmw_node_t node,
const rosidl_message_type_support_t *  type_support,
const char *  topic_name,
const rmw_qos_profile_t qos_policies 
)

◆ rmw_destroy_publisher()

rmw_ret_t rmw_destroy_publisher ( rmw_node_t node,
rmw_publisher_t publisher 
)

◆ rmw_publish()

rmw_ret_t rmw_publish ( const rmw_publisher_t publisher,
const void *  ros_message 
)

◆ rmw_publisher_count_matched_subscriptions()

rmw_ret_t rmw_publisher_count_matched_subscriptions ( const rmw_publisher_t publisher,
size_t *  subscription_count 
)

Retrieve the number of matched subscriptions to a publisher.

Query the underlying middleware to determine how many subscriptions are matched to a given publisher.

Parameters
[in]publisherthe publisher object to inspect
[out]subscription_countthe number of subscriptions matched
Returns
RMW_RET_OK if successful, or
RMW_RET_INVALID_ARGUMENT if either argument is null, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_publish_serialized_message()

rmw_ret_t rmw_publish_serialized_message ( const rmw_publisher_t publisher,
const rmw_serialized_message_t serialized_message 
)

Publish an already serialized message.

The publisher must already be registered with the correct message type support so that it can send serialized data corresponding to that type. This function sends the serialized byte stream directly over the wire without having to serialize the message first. A ROS message can be serialized manually using the rmw_serialize() function.

Parameters
publisherthe publisher object registered to send the message
serialized_messagethe serialized message holding the byte stream
Returns
RMW_RET_OK if successful, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_serialize()

rmw_ret_t rmw_serialize ( const void *  ros_message,
const rosidl_message_type_support_t *  type_support,
rmw_serialized_message_t serialized_message 
)

Serialize a ROS message into a rmw_serialized_message_t.

The ROS message is serialized into a byte stream contained within the rmw_serialized_message_t structure. The serialization format depends on the underlying middleware.

Parameters
ros_messagethe typed ROS message
type_supportthe typesupport for the ROS message
serialized_messagethe destination for the serialize ROS message
Returns
RMW_RET_OK if successful, or
RMW_RET_BAD_ALLOC if memory allocation failed, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_deserialize()

rmw_ret_t rmw_deserialize ( const rmw_serialized_message_t serialized_message,
const rosidl_message_type_support_t *  type_support,
void *  ros_message 
)

Deserialize a ROS message.

The given rmw_serialized_message_t's internal byte stream buffer is deserialized into the given ROS message. The ROS message must already be allocated and initialized, and must match the given typesupport structure. The serialization format expected in the rmw_serialized_message_t depends on the underlying middleware.

Parameters
serialized_messagethe serialized message holding the byte stream
type_supportthe typesupport for the typed ros message
ros_messagedestination for the deserialized ROS message
Returns
RMW_RET_OK if successful, or
RMW_RET_BAD_ALLOC if memory allocation failed, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_create_subscription()

rmw_subscription_t* rmw_create_subscription ( const rmw_node_t node,
const rosidl_message_type_support_t *  type_support,
const char *  topic_name,
const rmw_qos_profile_t qos_policies,
bool  ignore_local_publications 
)

◆ rmw_destroy_subscription()

rmw_ret_t rmw_destroy_subscription ( rmw_node_t node,
rmw_subscription_t subscription 
)

◆ rmw_subscription_count_matched_publishers()

rmw_ret_t rmw_subscription_count_matched_publishers ( const rmw_subscription_t subscription,
size_t *  publisher_count 
)

Retrieve the number of matched publishers to a subscription.

Query the underlying middleware to determine how many publishers are matched to a given subscription.

Parameters
[in]subscriptionthe subscription object to inspect
[out]publisher_countthe number of publishers matched
Returns
RMW_RET_OK if successful, or
RMW_RET_INVALID_ARGUMENT if either argument is null, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_take()

rmw_ret_t rmw_take ( const rmw_subscription_t subscription,
void *  ros_message,
bool *  taken 
)

◆ rmw_take_with_info()

rmw_ret_t rmw_take_with_info ( const rmw_subscription_t subscription,
void *  ros_message,
bool *  taken,
rmw_message_info_t message_info 
)

◆ rmw_take_serialized_message()

rmw_ret_t rmw_take_serialized_message ( const rmw_subscription_t subscription,
rmw_serialized_message_t serialized_message,
bool *  taken 
)

Take a message without deserializing it.

The message is taken in its serialized form. In contrast to rmw_take, the message is not deserialized in its ROS type but rather returned as a byte stream. The subscriber has to be registered for a specific type. But instead of receiving the message as its corresponding message type, it is taken as a byte stream. If needed, this byte stream can then be deserialized in a ROS message with a call to rmw_deserialize.

Parameters
subscriptionsubscription object to take from
serialized_messagethe destination in which to store the serialized message
takenboolean flag indicating if a message was taken or not
Returns
RMW_RET_OK if successful, or
RMW_RET_BAD_ALLOC if memory allocation failed, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_take_serialized_message_with_info()

rmw_ret_t rmw_take_serialized_message_with_info ( const rmw_subscription_t subscription,
rmw_serialized_message_t serialized_message,
bool *  taken,
rmw_message_info_t message_info 
)

Take a message without deserializing it and with its additional message information.

The same as rmw_take_serialized_message(), except it also includes the rmw_message_info_t.

Parameters
subscriptionsubscription object to take from
serialized_messagethe destination in which to store the serialized message
takenboolean flag indicating if a message was taken or not
message_infoa structure containing meta information about the taken message
Returns
RMW_RET_OK if successful, or
RMW_RET_BAD_ALLOC if memory allocation failed, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_create_client()

rmw_client_t* rmw_create_client ( const rmw_node_t node,
const rosidl_service_type_support_t *  type_support,
const char *  service_name,
const rmw_qos_profile_t qos_policies 
)

◆ rmw_destroy_client()

rmw_ret_t rmw_destroy_client ( rmw_node_t node,
rmw_client_t client 
)

◆ rmw_send_request()

rmw_ret_t rmw_send_request ( const rmw_client_t client,
const void *  ros_request,
int64_t *  sequence_id 
)

◆ rmw_take_response()

rmw_ret_t rmw_take_response ( const rmw_client_t client,
rmw_request_id_t request_header,
void *  ros_response,
bool *  taken 
)

◆ rmw_create_service()

rmw_service_t* rmw_create_service ( const rmw_node_t node,
const rosidl_service_type_support_t *  type_support,
const char *  service_name,
const rmw_qos_profile_t qos_policies 
)

◆ rmw_destroy_service()

rmw_ret_t rmw_destroy_service ( rmw_node_t node,
rmw_service_t service 
)

◆ rmw_take_request()

rmw_ret_t rmw_take_request ( const rmw_service_t service,
rmw_request_id_t request_header,
void *  ros_request,
bool *  taken 
)

◆ rmw_send_response()

rmw_ret_t rmw_send_response ( const rmw_service_t service,
rmw_request_id_t request_header,
void *  ros_response 
)

◆ rmw_create_guard_condition()

rmw_guard_condition_t* rmw_create_guard_condition ( rmw_context_t context)

Create a guard condition and return a handle to that guard condition.

This function can fail, and therefore return NULL, if:

  • context is NULL
  • context is invalid
  • memory allocation fails during guard condition creation
  • an unspecified error occurs

The context must be non-null and valid, i.e. it has been initialized by rmw_init() and has not been finalized by rmw_shutdown().


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No [1]
Lock-Free No [1]

[1] rmw implementation defined, check the implementation documentation

This should be defined by the rmw implementation.

Parameters
[in]contextinit context that this node should be associated with
Returns
rmw guard condition handle or NULL if there was an error

◆ rmw_destroy_guard_condition()

rmw_ret_t rmw_destroy_guard_condition ( rmw_guard_condition_t guard_condition)

Finalize a given guard condition handle, reclaim the resources, and deallocate the handle.

Parameters
guard_conditionthe guard condition handle to be destroyed
Returns
RMW_RET_OK if successful, or
RMW_RET_INVALID_ARGUMENT if guard_condition is null, or
RMW_RET_ERROR if an unexpected error occurs.

◆ rmw_trigger_guard_condition()

rmw_ret_t rmw_trigger_guard_condition ( const rmw_guard_condition_t guard_condition)

◆ rmw_create_wait_set()

rmw_wait_set_t* rmw_create_wait_set ( size_t  max_conditions)

Create a wait set to store conditions that the middleware will block on.

If max_conditions is 0, the wait set can store an unbounded number of conditions to wait on. If max_conditions is greater than 0, the number of conditions that can be attached to the wait set is bounded at max_conditions.

Parameters
[in]max_conditionsThe maximum number of conditions that can be attached to the wait set.
Returns
A pointer to the created wait set, NULL if an error occurred.

◆ rmw_destroy_wait_set()

rmw_ret_t rmw_destroy_wait_set ( rmw_wait_set_t wait_set)

◆ rmw_wait()

rmw_ret_t rmw_wait ( rmw_subscriptions_t subscriptions,
rmw_guard_conditions_t guard_conditions,
rmw_services_t services,
rmw_clients_t clients,
rmw_wait_set_t wait_set,
const rmw_time_t wait_timeout 
)

Waits on sets of different waitable entities and returns when one is ready.

Add conditions to the wait set and wait until a response comes in, or until the timeout is reached. The arrays contain type-erased representations of waitable entities. This function casts the pointers to middleware-specific conditions and adds them to the wait set.

The count variables in the arrays represents the number of valid pointers in the array. NULL pointers are in the array considered invalid. If they are encountered, an error is returned.

The array structs are allocated and deallocated outside of this function. They do not have any information about how much memory is allocated for the arrays.

After the wait wakes up, the entries in each array that correspond to conditions that were not triggered are set to NULL.

Parameters
subscriptionsArray of subscriptions to wait on
guard_conditionsArray of guard conditions to wait on
servicesArray of services to wait on
clientsArray of clients to wait on
wait_setStorage for the wait set
wait_timeoutIf NULL, block until a condition is ready. If zero, check only for immediately available conditions and don't block. Else, this represents the maximum time to wait for a response from the wait set.
Returns
RMW_RET_OK if success, or
RMW_RET_ERROR if error, or
RMW_RET_TIMEOUT if wait timed out.

◆ rmw_get_node_names()

rmw_ret_t rmw_get_node_names ( const rmw_node_t node,
rcutils_string_array_t node_names,
rcutils_string_array_t node_namespaces 
)

Return a list of node name and namespaces discovered via a node.

This function will return a list of node names and a list of node namespaces that are discovered via the middleware. The two lists represent pairs of namespace and name for each discovered node. The lists will be the same length and the same position will refer to the same node across lists.

The node parameter must not be NULL, and must point to a valid node.

The node_names parameter must not be NULL, and must point to a valid string array.

The node_namespaces parameter must not be NULL, and must point to a valid string array.

This function does manipulate heap memory. This function is not thread-safe. This function is lock-free.

Parameters
[in]nodethe handle to the node being used to query the ROS graph
[out]node_namesa list of discovered node names
[out]node_namespacesa list of discovered node namespaces
Returns
RMW_RET_OK if node the query was made successfully, or
RMW_RET_ERROR if an unspecified error occurs.

◆ rmw_count_publishers()

rmw_ret_t rmw_count_publishers ( const rmw_node_t node,
const char *  topic_name,
size_t *  count 
)

◆ rmw_count_subscribers()

rmw_ret_t rmw_count_subscribers ( const rmw_node_t node,
const char *  topic_name,
size_t *  count 
)

◆ rmw_get_gid_for_publisher()

rmw_ret_t rmw_get_gid_for_publisher ( const rmw_publisher_t publisher,
rmw_gid_t gid 
)

◆ rmw_compare_gids_equal()

rmw_ret_t rmw_compare_gids_equal ( const rmw_gid_t gid1,
const rmw_gid_t gid2,
bool *  result 
)

◆ rmw_service_server_is_available()

rmw_ret_t rmw_service_server_is_available ( const rmw_node_t node,
const rmw_client_t client,
bool *  is_available 
)

Check if a service server is available for the given service client.

This function will return true for is_available if there is a service server available for the given client.

The node parameter must not be NULL, and must point to a valid node.

The client parameter must not be NULL, and must point to a valid client.

The given client and node must match, i.e. the client must have been created using the given node.

The is_available parameter must not be NULL, and must point to a bool variable. The result of the check will be stored in the is_available parameter.

This function does manipulate heap memory. This function is not thread-safe. This function is lock-free.

Parameters
[in]nodethe handle to the node being used to query the ROS graph
[in]clientthe handle to the service client being queried
[out]is_availableset to true if there is a service server available, else false
Returns
RMW_RET_OK if node the check was made successfully, or
RMW_RET_ERROR if an unspecified error occurs.

◆ rmw_set_log_severity()

rmw_ret_t rmw_set_log_severity ( rmw_log_severity_t  severity)