rmw
master
C API providing a middleware abstraction layer which is used to implement the rest of ROS.
|
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "rcutils/macros.h"
#include "rcutils/types.h"
#include "rosidl_runtime_c/message_type_support_struct.h"
#include "rosidl_runtime_c/service_type_support_struct.h"
#include "rosidl_runtime_c/sequence_bound.h"
#include "rmw/init.h"
#include "rmw/macros.h"
#include "rmw/qos_profiles.h"
#include "rmw/subscription_options.h"
#include "rmw/message_sequence.h"
#include "rmw/types.h"
#include "rmw/visibility_control.h"
Go to the source code of this file.
Functions | |
const char * | rmw_get_implementation_identifier (void) |
Get the name of the rmw implementation being used. More... | |
const char * | rmw_get_serialization_format (void) |
Get the unique serialization format for this middleware. More... | |
rmw_node_t * | rmw_create_node (rmw_context_t *context, const char *name, const char *namespace_, size_t domain_id, bool localhost_only) |
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... | |
RCUTILS_DEPRECATED_WITH_MSG ("rmw_node_assert_liveliness implementation was removed." " If manual liveliness assertion is needed, use MANUAL_BY_TOPIC.") rmw_ret_t rmw_node_assert_liveliness(const rmw_node_t *node) | |
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. More... | |
rmw_ret_t | rmw_init_publisher_allocation (const rosidl_message_type_support_t *type_support, const rosidl_runtime_c__Sequence__bound *message_bounds, rmw_publisher_allocation_t *allocation) |
Initialize a publisher allocation to be used with later publications. More... | |
rmw_ret_t | rmw_fini_publisher_allocation (rmw_publisher_allocation_t *allocation) |
Destroy a publisher allocation object. More... | |
rmw_publisher_options_t | rmw_get_default_publisher_options (void) |
Return a rmw_publisher_options_t initialized with default values. More... | |
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, const rmw_publisher_options_t *publisher_options) |
Create and return an rmw publisher. More... | |
rmw_ret_t | rmw_destroy_publisher (rmw_node_t *node, rmw_publisher_t *publisher) |
rmw_ret_t | rmw_borrow_loaned_message (const rmw_publisher_t *publisher, const rosidl_message_type_support_t *type_support, void **ros_message) |
Borrow a loaned message. More... | |
rmw_ret_t | rmw_return_loaned_message_from_publisher (const rmw_publisher_t *publisher, void *loaned_message) |
Return a loaned message previously borrow from a publisher. More... | |
rmw_ret_t | rmw_publish (const rmw_publisher_t *publisher, const void *ros_message, rmw_publisher_allocation_t *allocation) |
Publish a given ros_message. More... | |
rmw_ret_t | rmw_publish_loaned_message (const rmw_publisher_t *publisher, void *ros_message, rmw_publisher_allocation_t *allocation) |
Publish a loaned ros_message. More... | |
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_publisher_get_actual_qos (const rmw_publisher_t *publisher, rmw_qos_profile_t *qos) |
Retrieve the actual qos settings of the publisher. More... | |
rmw_ret_t | rmw_publish_serialized_message (const rmw_publisher_t *publisher, const rmw_serialized_message_t *serialized_message, rmw_publisher_allocation_t *allocation) |
Publish an already serialized message. More... | |
rmw_ret_t | rmw_get_serialized_message_size (const rosidl_message_type_support_t *type_support, const rosidl_runtime_c__Sequence__bound *message_bounds, size_t *size) |
Compute the size of a serialized message. More... | |
rmw_ret_t | rmw_publisher_assert_liveliness (const rmw_publisher_t *publisher) |
Manually assert that this Publisher is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC) 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_ret_t | rmw_init_subscription_allocation (const rosidl_message_type_support_t *type_support, const rosidl_runtime_c__Sequence__bound *message_bounds, rmw_subscription_allocation_t *allocation) |
Initialize a subscription allocation to be used with later take s. More... | |
rmw_ret_t | rmw_fini_subscription_allocation (rmw_subscription_allocation_t *allocation) |
Destroy a publisher allocation object. More... | |
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, const rmw_subscription_options_t *subscription_options) |
Create and return an rmw subscription. More... | |
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_subscription_get_actual_qos (const rmw_subscription_t *subscription, rmw_qos_profile_t *qos) |
Retrieve the actual qos settings of the subscription. More... | |
rmw_ret_t | rmw_take (const rmw_subscription_t *subscription, void *ros_message, bool *taken, rmw_subscription_allocation_t *allocation) |
Take an incoming message from a subscription. More... | |
rmw_ret_t | rmw_take_with_info (const rmw_subscription_t *subscription, void *ros_message, bool *taken, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation) |
Take an incoming message from a subscription with additional metadata. More... | |
rmw_ret_t | rmw_take_sequence (const rmw_subscription_t *subscription, size_t count, rmw_message_sequence_t *message_sequence, rmw_message_info_sequence_t *message_info_sequence, size_t *taken, rmw_subscription_allocation_t *allocation) |
Take multiple incoming messages from a subscription with additional metadata. More... | |
rmw_ret_t | rmw_take_serialized_message (const rmw_subscription_t *subscription, rmw_serialized_message_t *serialized_message, bool *taken, rmw_subscription_allocation_t *allocation) |
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, rmw_subscription_allocation_t *allocation) |
Take a message without deserializing it and with its additional message information. More... | |
rmw_ret_t | rmw_take_loaned_message (const rmw_subscription_t *subscription, void **loaned_message, bool *taken, rmw_subscription_allocation_t *allocation) |
Take a loaned message. More... | |
rmw_ret_t | rmw_take_loaned_message_with_info (const rmw_subscription_t *subscription, void **loaned_message, bool *taken, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation) |
Take a loaned message and with its additional message information. More... | |
rmw_ret_t | rmw_return_loaned_message_from_subscription (const rmw_subscription_t *subscription, void *loaned_message) |
Return a loaned message previously taken from a subscription. More... | |
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) |
Create an rmw client to communicate with the specified service. More... | |
rmw_ret_t | rmw_destroy_client (rmw_node_t *node, rmw_client_t *client) |
Destroy and unregister a service client. More... | |
rmw_ret_t | rmw_send_request (const rmw_client_t *client, const void *ros_request, int64_t *sequence_id) |
Send a service request to the rmw server. More... | |
rmw_ret_t | rmw_take_response (const rmw_client_t *client, rmw_service_info_t *request_header, void *ros_response, bool *taken) |
Attempt to get the response from a service request. More... | |
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) |
Create an rmw service server that responds to requests. More... | |
rmw_ret_t | rmw_destroy_service (rmw_node_t *node, rmw_service_t *service) |
Destroy and unregister the service from this node. More... | |
rmw_ret_t | rmw_take_request (const rmw_service_t *service, rmw_service_info_t *request_header, void *ros_request, bool *taken) |
Attempt to take a request from this service's request buffer. More... | |
rmw_ret_t | rmw_send_response (const rmw_service_t *service, rmw_request_id_t *request_header, void *ros_response) |
Send response to a client's request. More... | |
rmw_guard_condition_t * | rmw_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_t * | rmw_create_wait_set (rmw_context_t *context, 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) |
Destroy and free memory of this wait_set. More... | |
rmw_ret_t | rmw_wait (rmw_subscriptions_t *subscriptions, rmw_guard_conditions_t *guard_conditions, rmw_services_t *services, rmw_clients_t *clients, rmw_events_t *events, 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_get_node_names_with_enclaves (const rmw_node_t *node, rcutils_string_array_t *node_names, rcutils_string_array_t *node_namespaces, rcutils_string_array_t *enclaves) |
Return a list of node name and namespaces discovered via a node with its enclave. More... | |
rmw_ret_t | rmw_count_publishers (const rmw_node_t *node, const char *topic_name, size_t *count) |
Count the number of publishers matching a topic name. More... | |
rmw_ret_t | rmw_count_subscribers (const rmw_node_t *node, const char *topic_name, size_t *count) |
Count the number of subscribers matching a topic name. More... | |
rmw_ret_t | rmw_get_gid_for_publisher (const rmw_publisher_t *publisher, rmw_gid_t *gid) |
Get the unique identifier of the publisher. More... | |
rmw_ret_t | rmw_compare_gids_equal (const rmw_gid_t *gid1, const rmw_gid_t *gid2, bool *result) |
Check if two gid objects are the same. More... | |
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) |
Set the current log severity. More... | |
const char* rmw_get_implementation_identifier | ( | void | ) |
Get the name of the rmw implementation being used.
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.
rmw_node_t* rmw_create_node | ( | rmw_context_t * | context, |
const char * | name, | ||
const char * | namespace_, | ||
size_t | domain_id, | ||
bool | localhost_only | ||
) |
Create a node and return a handle to that node.
This function can fail, and therefore return NULL
, if:
NULL
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.
[in] | context | init context that this node should be associated with |
[in] | name | the node name |
[in] | namespace_ | the node namespace |
[in] | domain_id | the id of the domain that the node should join |
[in] | security_options | the security configurations for the node |
[in] | localhost_only | whenever to use loopback only for communication or default network interfaces. |
NULL
if there was an error rmw_ret_t rmw_destroy_node | ( | rmw_node_t * | node | ) |
Finalize a given node handle, reclaim the resources, and deallocate the node handle.
The method may assume - but should verify - that all publishers, subscribers, services, and clients created from this node have already been destroyed. If the rmw implementation chooses to verify instead of assume, it should return RMW_RET_ERROR
and set a human readable error message if any entity created from this node has not yet been destroyed.
[in] | node | the node handle to be destroyed |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if node is null, or RMW_RET_ERROR
if an unexpected error occurs. RCUTILS_DEPRECATED_WITH_MSG | ( | "rmw_node_assert_liveliness implementation was removed." " If manual liveliness assertion is | needed, |
use MANUAL_BY_TOPIC." | |||
) | const |
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:
NULL
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 |
[in] | node | pointer to the rmw node |
NULL
rmw_ret_t rmw_init_publisher_allocation | ( | const rosidl_message_type_support_t * | type_support, |
const rosidl_runtime_c__Sequence__bound * | message_bounds, | ||
rmw_publisher_allocation_t * | allocation | ||
) |
Initialize a publisher allocation to be used with later publications.
This creates an allocation object that can be used in conjunction with the rmw_publish method to perform more carefully control memory allocations.
This will allow the middleware to preallocate the correct amount of memory for a given message type and message bounds. As allocation is performed in this method, it will not be necessary to allocate in the rmw_publish
method.
[in] | type_support | Type support of the message to be preallocated. |
[in] | message_bounds | Bounds structure of the message to be preallocated. |
[out] | allocation | Allocation structure to be passed to rmw_publish . |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if an argument is null, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_fini_publisher_allocation | ( | rmw_publisher_allocation_t * | allocation | ) |
Destroy a publisher allocation object.
This deallocates any memory allocated by rmw_init_publisher_allocation
.
[in] | allocation | Allocation object to be destroyed. |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if argument is null, or RMW_RET_ERROR
if an unexpected error occurs. rmw_publisher_options_t rmw_get_default_publisher_options | ( | void | ) |
Return a rmw_publisher_options_t initialized with default values.
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, | ||
const rmw_publisher_options_t * | publisher_options | ||
) |
Create and return an rmw publisher.
\TODO(wjwwood): add detailed documentation, adding a not about one of the arguments for now.
The argument publisher_options
must not be nullptr.
[in] | publisher_options | options for configuring the publisher |
rmw_ret_t rmw_destroy_publisher | ( | rmw_node_t * | node, |
rmw_publisher_t * | publisher | ||
) |
rmw_ret_t rmw_borrow_loaned_message | ( | const rmw_publisher_t * | publisher, |
const rosidl_message_type_support_t * | type_support, | ||
void ** | ros_message | ||
) |
Borrow a loaned message.
The memory allocated for the ros message belongs to the middleware and must not be deallocated. A call to
In order to react to failures, the ros message is passed by pointer as an output parameter. Therefore, the pointer to the ros message has to be null
and not previously allocated or else that memory is lost.
[in] | publisher | Publisher to which the allocated message is associated. |
[in] | type_support | Typesupport to which the internal ros message is allocated. |
[out] | ros_message | The pointer to be filled with a valid ros message by the middleware. |
RMW_RET_OK
if the ros message was correctly initialized, or RMW_RET_INVALID_ARGUMENT
if an argument other than the ros message is null, or RMW_RET_BAD_ALLOC
if the ros message could not be correctly created, or RMW_RET_UNSUPPORTED
if the rmw_implementation does not support loaned_message, or RMW_RET_ERROR
if an unexpected error occured. rmw_ret_t rmw_return_loaned_message_from_publisher | ( | const rmw_publisher_t * | publisher, |
void * | loaned_message | ||
) |
Return a loaned message previously borrow from a publisher.
The ownership of the passed in ros message will be transferred back to the middleware. The middleware might deallocate and destroy the message so that the pointer is no longer guaranteed to be valid after this call.
[in] | publisher | Publisher to which the loaned message is associated. |
[in] | loaned_message | Loaned message to be returned. |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if an argument is null, or RMW_RET_UNSUPPORTED
if the rmw_implementation does not support loaned_message, or RMW_RET_ERROR
if an unexpected error occurs and no message can be initialized. rmw_ret_t rmw_publish | ( | const rmw_publisher_t * | publisher, |
const void * | ros_message, | ||
rmw_publisher_allocation_t * | allocation | ||
) |
Publish a given ros_message.
Publish a given ROS message via a publisher.
[in] | publisher | Publisher to be used to send message. |
[in] | ros_message | Message to be sent. |
[in] | allocation | Specify preallocated memory to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if publisher or ros_message is null, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_publish_loaned_message | ( | const rmw_publisher_t * | publisher, |
void * | ros_message, | ||
rmw_publisher_allocation_t * | allocation | ||
) |
Publish a loaned ros_message.
Publish a loaned ROS message via a publisher and return ownership of the loaned message back to the middleware.
In contrast to
rmw_publish
the ownership of the ros message is being transferred to the middleware which might deallocate the memory for it. Similar to rmw_return_loaned_message_from_publisher
the passed in ros message might not be valid after this call and thus should only be called with messages previously loaned with a call to rmw_borrow_loaned_message
.[in] | publisher | Publisher to be used to send message. |
[in] | ros_message | Message to be sent. |
[in] | allocation | Specify preallocated memory to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if publisher or ros_message is null, or RMW_RET_UNSUPPORTED
if the rmw_implementation does not support loaned_message, or RMW_RET_ERROR
if an unexpected error occurs. 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.
[in] | publisher | the publisher object to inspect |
[out] | subscription_count | the number of subscriptions matched |
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_ret_t rmw_publisher_get_actual_qos | ( | const rmw_publisher_t * | publisher, |
rmw_qos_profile_t * | qos | ||
) |
Retrieve the actual qos settings of the publisher.
Query the underlying middleware to determine the qos settings of the publisher. The actual configuration applied when using RMW_*_SYSTEM_DEFAULT can only be resolved after the creation of the publisher, and it depends on the underlying rmw implementation. If the underlying setting in use can't be represented in ROS terms, it will be set to RMW_*_UNKNOWN. The value of avoid_ros_namespace_conventions field is not resolved with this function. The rcl function rcl_publisher_get_actual_qos resolves it.
[in] | publisher | the publisher object to inspect |
[out] | qos | the actual qos settings |
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_ret_t rmw_publish_serialized_message | ( | const rmw_publisher_t * | publisher, |
const rmw_serialized_message_t * | serialized_message, | ||
rmw_publisher_allocation_t * | allocation | ||
) |
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.
[in] | publisher | The publisher object registered to send the message. |
[in] | serialized_message | The serialized message holding the byte stream. |
[in] | allocation | Specify preallocated memory to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_get_serialized_message_size | ( | const rosidl_message_type_support_t * | type_support, |
const rosidl_runtime_c__Sequence__bound * | message_bounds, | ||
size_t * | size | ||
) |
Compute the size of a serialized message.
Given a message definition and bounds, compute the serialized size.
[in] | type_support | The type support of the message to compute. |
[in] | bounds | Artifical bounds to use on unbounded fields. |
[out] | size | The computed size of the serialized message. |
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_ret_t rmw_publisher_assert_liveliness | ( | const rmw_publisher_t * | publisher | ) |
Manually assert that this Publisher is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC)
If the rmw Liveliness policy is set to RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC, the creator of this publisher may manually call assert_liveliness
at some point in time to signal to the rest of the system that this Node is still alive.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | Yes |
Uses Atomics | No |
Lock-Free | Yes |
[in] | publisher | handle to the publisher that needs liveliness to be asserted |
RMW_RET_OK
if the liveliness assertion was completed successfully, or RMW_RET_ERROR
if an unspecified error occurs, or RMW_RET_UNSUPPORTED
if the rmw implementation does not support asserting liveliness. 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.
[in] | ros_message | the typed ROS message |
[in] | type_support | the typesupport for the ROS message |
[out] | serialized_message | the destination for the serialize ROS message |
RMW_RET_OK
if successful, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_ERROR
if an unexpected error occurs. 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.
[in] | serialized_message | the serialized message holding the byte stream |
[in] | type_support | the typesupport for the typed ros message |
[out] | ros_message | destination for the deserialized ROS message |
RMW_RET_OK
if successful, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_init_subscription_allocation | ( | const rosidl_message_type_support_t * | type_support, |
const rosidl_runtime_c__Sequence__bound * | message_bounds, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
Initialize a subscription allocation to be used with later take
s.
This creates an allocation object that can be used in conjunction with the rmw_take method to perform more carefully control memory allocations.
This will allow the middleware to preallocate the correct amount of memory for a given message type and message bounds. As allocation is performed in this method, it will not be necessary to allocate in the rmw_take
method.
[in] | type_support | Type support of the message to be preallocated. |
[in] | message_bounds | Bounds structure of the message to be preallocated. |
[out] | allocation | Allocation structure to be passed to rmw_take . |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if an argument is null, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_fini_subscription_allocation | ( | rmw_subscription_allocation_t * | allocation | ) |
Destroy a publisher allocation object.
This deallocates memory allocated by rmw_init_subscription_allocation
.
[in] | allocation | Allocation object to be destroyed. |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if argument is null, or RMW_RET_ERROR
if an unexpected error occurs. 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, | ||
const rmw_subscription_options_t * | subscription_options | ||
) |
Create and return an rmw subscription.
\TODO(wjwwood): add detailed documentation, adding a not about one of the arguments for now.
The argument subscription_options
must not be nullptr.
[in] | subscription_options | options for configuring the subscription |
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.
Query the underlying middleware to determine how many publishers are matched to a given subscription.
[in] | subscription | the subscription object to inspect |
[out] | publisher_count | the number of publishers matched |
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_ret_t rmw_subscription_get_actual_qos | ( | const rmw_subscription_t * | subscription, |
rmw_qos_profile_t * | qos | ||
) |
Retrieve the actual qos settings of the subscription.
Query the underlying middleware to determine the qos settings of the subscription. The actual configuration applied when using RMW_*_SYSTEM_DEFAULT can only be resolved after the creation of the subscription, and it depends on the underlying rmw implementation. If the underlying setting in use can't be represented in ROS terms, it will be set to RMW_*_UNKNOWN. The value of avoid_ros_namespace_conventions field is not resolved with this function. The rcl function rcl_subscription_get_actual_qos resolves it.
[in] | subscription | the subscription object to inspect |
[out] | qos | the actual qos settings |
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_ret_t rmw_take | ( | const rmw_subscription_t * | subscription, |
void * | ros_message, | ||
bool * | taken, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
Take an incoming message from a subscription.
Take an incoming ROS message from a given subscription.
[in] | subscription | The subscription object to take from. |
[out] | ros_message | The ROS message data on success. |
[out] | taken | Boolean flag indicating if a message was taken or not. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_take_with_info | ( | const rmw_subscription_t * | subscription, |
void * | ros_message, | ||
bool * | taken, | ||
rmw_message_info_t * | message_info, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
Take an incoming message from a subscription with additional metadata.
Take an incoming ROS message from a given subscription.
[in] | subscription | The subscription object to take from. |
[out] | ros_message | The ROS message data on success. |
[out] | taken | Boolean flag indicating if a message was taken or not. |
[out] | message_info | Additional message metadata. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_take_sequence | ( | const rmw_subscription_t * | subscription, |
size_t | count, | ||
rmw_message_sequence_t * | message_sequence, | ||
rmw_message_info_sequence_t * | message_info_sequence, | ||
size_t * | taken, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
Take multiple incoming messages from a subscription with additional metadata.
Take a sequence of ROS messgages from a given subscription.
While count
messages may be requested, fewer messages may be available on the subscription. In this case, only the currently available messages will be returned. The taken
flag indicates the number of messages actually taken. The method will return RMW_RET_OK
even in the case that fewer (or zero) messages were retrieved. from the subscription, and will RMW_RET_ERROR
in the case of unexpected errors. In the case that count
is zero, the function will return RMW_RET_INVALID_ARGUMENT
.
message_sequence
and message_info_sequence
should be initialized and have sufficient capacity. It is not critical that the sequence sizes match, and they may be reused from previous calls. Both must be valid (not NULL) for the method to run successfully.
[in] | subscription | The subscription object to take from. |
[in] | count | Number of messages to attempt to take. |
[out] | message_sequence | The sequence of ROS message data on success. |
[out] | message_info_sequence | The sequence of additional message metadata on success. |
[out] | taken | Number of messages actually taken from subscription. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_INVALID_ARGUMENT
if an argument is invalid, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_INCORRECT_RMW_IMPLEMENTATION
if the rmw implementation does not match, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_take_serialized_message | ( | const rmw_subscription_t * | subscription, |
rmw_serialized_message_t * | serialized_message, | ||
bool * | taken, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
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.
[in] | subscription | Subscription object to take from. |
[out] | serialized_message | The destination in which to store the serialized message. |
[out] | taken | Boolean flag indicating if a message was taken or not. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_ERROR
if an unexpected error occurs. 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, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
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.
[in] | subscription | Subscription object to take from. |
[out] | serialized_message | The destination in which to store the serialized message. |
[out] | taken | Boolean flag indicating if a message was taken or not. |
[out] | message_info | A structure containing meta information about the taken message. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_take_loaned_message | ( | const rmw_subscription_t * | subscription, |
void ** | loaned_message, | ||
bool * | taken, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
Take a loaned message.
If capable, the middleware can loan messages containing incoming messages. The message is owned by the middleware and thus has to be returned with a call to
[in] | subscription | Subscription object to take from. |
[in,out] | loaned_message | The destination in which to store the loaned message. |
[out] | taken | Boolean flag indicating if a message was taken or not. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_UNSUPPORTED
if the rmw_implementation does not support loaned_message, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_take_loaned_message_with_info | ( | const rmw_subscription_t * | subscription, |
void ** | loaned_message, | ||
bool * | taken, | ||
rmw_message_info_t * | message_info, | ||
rmw_subscription_allocation_t * | allocation | ||
) |
Take a loaned message and with its additional message information.
If capable, the middleware can loan messages containing incoming messages. The message is owned by the middleware and thus has to be returned with a call to
[in] | subscription | Subscription object to take from. |
[in,out] | loaned_message | The destination in which to store the loaned message. |
[out] | taken | Boolean flag indicating if a message was taken or not. |
[out] | message_info | A structure containing meta information about the taken message. |
[in] | allocation | Preallocated buffer to use (may be NULL). |
RMW_RET_OK
if successful, or RMW_RET_BAD_ALLOC
if memory allocation failed, or RMW_RET_UNSUPPORTED
if the rmw_implementation does not support loaned_message, or RMW_RET_ERROR
if an unexpected error occurs. rmw_ret_t rmw_return_loaned_message_from_subscription | ( | const rmw_subscription_t * | subscription, |
void * | loaned_message | ||
) |
Return a loaned message previously taken from a subscription.
After the taking a loaned message from the middleware, the middleware has to keep the memory for the loaned message alive and valid as long as the user is working with that loan. In order to indicate that the loaned message is no longer needed, the call to
[in] | subscription | The subscription instance which loaned the message. |
[in] | loaned_message | The message to be released. |
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 | ||
) |
Create an rmw client to communicate with the specified service.
[in] | node | Handle to node with which to register this client |
[in] | type_support | The type_support of this rosidl service |
[in] | service_name | The name of the ROS 2 service to connect with |
[in] | qos_policies | The QoS profile policies to utilize for this connection |
nullptr
if not rmw_ret_t rmw_destroy_client | ( | rmw_node_t * | node, |
rmw_client_t * | client | ||
) |
Destroy and unregister a service client.
[in] | node | The associated node whose client will be destroyed |
[in] | client | The service client to destroy |
rmw_ret_t rmw_send_request | ( | const rmw_client_t * | client, |
const void * | ros_request, | ||
int64_t * | sequence_id | ||
) |
Send a service request to the rmw server.
[in] | client | The connected client over which to send this request |
[in] | ros_request | the request message to send to the server |
[out] | sequence_id | A unique identification value to identify this request |
rmw_ret_t rmw_take_response | ( | const rmw_client_t * | client, |
rmw_service_info_t * | request_header, | ||
void * | ros_response, | ||
bool * | taken | ||
) |
Attempt to get the response from a service request.
[in] | client | The connected client to check on this request |
[out] | request_header | Header response information |
[out] | ros_response | The response of this service request, |
[out] | taken | True if the response was taken, false otherwise |
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 | ||
) |
Create an rmw service server that responds to requests.
[in] | node | The node that responds the service requests |
[in] | type_support | The type support description of this service |
[in] | service_name | The name of this service advertised across the ROS graph |
[in] | qos_policies | The QoS profile policies to utilize for connections |
rmw_ret_t rmw_destroy_service | ( | rmw_node_t * | node, |
rmw_service_t * | service | ||
) |
Destroy and unregister the service from this node.
[in] | node | The node that owns the service that is being destroyed |
[in] | service | Pointer to the service type created in rmw_create_service |
rmw_ret_t rmw_take_request | ( | const rmw_service_t * | service, |
rmw_service_info_t * | request_header, | ||
void * | ros_request, | ||
bool * | taken | ||
) |
Attempt to take a request from this service's request buffer.
[in] | service | service object that responds to these requests |
[out] | request_header | Request information header with writer guid and sequence number |
[out] | ros_request | The deserialized ros_request, and is unmodified if there are no requests |
[out] | taken | true if the request was taken, otherwise false |
rmw_ret_t rmw_send_response | ( | const rmw_service_t * | service, |
rmw_request_id_t * | request_header, | ||
void * | ros_response | ||
) |
Send response to a client's request.
[in] | service | The service that responding to this request |
[in] | request_header | The request header obtained when this request was taken |
[in] | ros_response | The response message to send to the client |
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:
NULL
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.
[in] | context | init context that this node should be associated with |
NULL
if there was an error 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.
[in] | guard_condition | the guard condition handle to be destroyed |
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_ret_t rmw_trigger_guard_condition | ( | const rmw_guard_condition_t * | guard_condition | ) |
rmw_wait_set_t* rmw_create_wait_set | ( | rmw_context_t * | context, |
size_t | max_conditions | ||
) |
Create a wait set to store conditions that the middleware will block on.
This function can fail, and therefore return NULL
, if:
NULL
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
.
[in] | context | init context that this node should be associated with |
[in] | max_conditions | The maximum number of conditions that can be attached to the wait set. |
NULL
if an error occurred. rmw_ret_t rmw_destroy_wait_set | ( | rmw_wait_set_t * | wait_set | ) |
Destroy and free memory of this wait_set.
[in] | wait_set | The wait_set object to destroy |
rmw_ret_t rmw_wait | ( | rmw_subscriptions_t * | subscriptions, |
rmw_guard_conditions_t * | guard_conditions, | ||
rmw_services_t * | services, | ||
rmw_clients_t * | clients, | ||
rmw_events_t * | events, | ||
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
.
[in] | subscriptions | Array of subscriptions to wait on |
[in] | guard_conditions | Array of guard conditions to wait on |
[in] | services | Array of services to wait on |
[in] | clients | Array of clients to wait on |
[in] | wait_set | Storage for the wait set |
[in] | wait_timeout | If 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. |
RMW_RET_OK
if success, or RMW_RET_ERROR
if error, or RMW_RET_TIMEOUT
if wait timed out. 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.
[in] | node | the handle to the node being used to query the ROS graph |
[out] | node_names | a list of discovered node names |
[out] | node_namespaces | a list of discovered node namespaces |
RMW_RET_OK
if node the query was made successfully, or RMW_RET_ERROR
if an unspecified error occurs. rmw_ret_t rmw_get_node_names_with_enclaves | ( | const rmw_node_t * | node, |
rcutils_string_array_t * | node_names, | ||
rcutils_string_array_t * | node_namespaces, | ||
rcutils_string_array_t * | enclaves | ||
) |
Return a list of node name and namespaces discovered via a node with its enclave.
Similar to rmw_get_node_names, but it also provides the enclave name.
[in] | node | the handle to the node being used to query the ROS graph |
[out] | node_names | a list of discovered node names |
[out] | node_namespaces | a list of discovered node namespaces |
[out] | enclaves | list of discovered nodes' enclave names |
RMW_RET_OK
if node the query was made successfully, or RMW_RET_ERROR
if an unspecified error occurs. rmw_ret_t rmw_count_publishers | ( | const rmw_node_t * | node, |
const char * | topic_name, | ||
size_t * | count | ||
) |
Count the number of publishers matching a topic name.
[in] | node | rmw node connected to the ROS graph |
[in] | topic_name | The name of the topic to match under possible prefixes |
[out] | count | The number of publishers matching the topic name |
rmw_ret_t rmw_count_subscribers | ( | const rmw_node_t * | node, |
const char * | topic_name, | ||
size_t * | count | ||
) |
Count the number of subscribers matching a topic name.
[in] | node | rmw node connected to the ROS graph |
[in] | topic_name | The name of the topic to match under possible prefixes |
[out] | count | The number of subscribers matching the topic name |
rmw_ret_t rmw_get_gid_for_publisher | ( | const rmw_publisher_t * | publisher, |
rmw_gid_t * | gid | ||
) |
Get the unique identifier of the publisher.
[in] | publisher | The publisher to get the gid of |
[out] | gid | The resulting gid |
Check if two gid objects are the same.
[in] | gid1 | One gid1 to compare |
[in] | gid2 | The other gid to compare |
[out] | bool | true if the gid objects match, false otherwise |
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.
[in] | node | the handle to the node being used to query the ROS graph |
[in] | client | the handle to the service client being queried |
[out] | is_available | set to true if there is a service server available, else false |
RMW_RET_OK
if node the check was made successfully, or RMW_RET_ERROR
if an unspecified error occurs. rmw_ret_t rmw_set_log_severity | ( | rmw_log_severity_t | severity | ) |
Set the current log severity.
[in] | severity | The log severity to set |