rmw  master
C API providing a middleware abstraction layer which is used to implement the rest of ROS.
rmw.h
Go to the documentation of this file.
1 // Copyright 2014-2017 Open Source Robotics Foundation, Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
78 #ifndef RMW__RMW_H_
79 #define RMW__RMW_H_
80 
81 #ifdef __cplusplus
82 extern "C"
83 {
84 #endif
85 
86 #include <stdbool.h>
87 #include <stddef.h>
88 #include <stdint.h>
89 
90 #include "rcutils/types.h"
91 
92 #include "rosidl_generator_c/message_bounds_struct.h"
93 #include "rosidl_generator_c/message_type_support_struct.h"
94 #include "rosidl_generator_c/service_type_support_struct.h"
95 
96 #include "rmw/init.h"
97 #include "rmw/macros.h"
98 #include "rmw/qos_profiles.h"
99 #include "rmw/types.h"
100 #include "rmw/visibility_control.h"
101 
102 RMW_PUBLIC
103 RMW_WARN_UNUSED
104 const char *
105 rmw_get_implementation_identifier(void);
106 
108 
119 RMW_PUBLIC
120 RMW_WARN_UNUSED
121 const char *
122 rmw_get_serialization_format(void);
123 
124 // TODO(wjwwood): refactor this API to return a return code when updated to use an allocator
126 
164 RMW_PUBLIC
165 RMW_WARN_UNUSED
166 rmw_node_t *
167 rmw_create_node(
168  rmw_context_t * context,
169  const char * name,
170  const char * namespace_,
171  size_t domain_id,
172  const rmw_node_security_options_t * security_options);
173 
175 
181 RMW_PUBLIC
182 RMW_WARN_UNUSED
183 rmw_ret_t
184 rmw_destroy_node(rmw_node_t * node);
185 
187 
205 RMW_PUBLIC
206 RMW_WARN_UNUSED
207 rmw_ret_t
208 rmw_node_assert_liveliness(const rmw_node_t * node);
209 
211 
237 RMW_PUBLIC
238 RMW_WARN_UNUSED
239 const rmw_guard_condition_t *
240 rmw_node_get_graph_guard_condition(const rmw_node_t * node);
241 
243 
259 RMW_PUBLIC
260 RMW_WARN_UNUSED
261 rmw_ret_t
262 rmw_init_publisher_allocation(
263  const rosidl_message_type_support_t * type_support,
264  const rosidl_message_bounds_t * message_bounds,
265  rmw_publisher_allocation_t * allocation);
266 
268 
276 RMW_PUBLIC
277 RMW_WARN_UNUSED
278 rmw_ret_t
279 rmw_fini_publisher_allocation(
280  rmw_publisher_allocation_t * allocation);
281 
282 RMW_PUBLIC
283 RMW_WARN_UNUSED
284 rmw_publisher_t *
285 rmw_create_publisher(
286  const rmw_node_t * node,
287  const rosidl_message_type_support_t * type_support,
288  const char * topic_name,
289  const rmw_qos_profile_t * qos_policies);
290 
291 RMW_PUBLIC
292 RMW_WARN_UNUSED
293 rmw_ret_t
294 rmw_destroy_publisher(rmw_node_t * node, rmw_publisher_t * publisher);
295 
297 
307 RMW_PUBLIC
308 RMW_WARN_UNUSED
309 rmw_ret_t
310 rmw_publish(
311  const rmw_publisher_t * publisher,
312  const void * ros_message,
313  rmw_publisher_allocation_t * allocation);
314 
316 
326 RMW_PUBLIC
327 RMW_WARN_UNUSED
328 rmw_ret_t
329 rmw_publisher_count_matched_subscriptions(
330  const rmw_publisher_t * publisher,
331  size_t * subscription_count);
332 
334 
352 RMW_PUBLIC
353 RMW_WARN_UNUSED
354 rmw_ret_t
355 rmw_publisher_get_actual_qos(
356  const rmw_publisher_t * publisher,
357  rmw_qos_profile_t * qos);
358 
360 
373 RMW_PUBLIC
374 RMW_WARN_UNUSED
375 rmw_ret_t
376 rmw_publish_serialized_message(
377  const rmw_publisher_t * publisher,
378  const rmw_serialized_message_t * serialized_message,
379  rmw_publisher_allocation_t * allocation);
380 
382 
392 RMW_PUBLIC
393 RMW_WARN_UNUSED
394 rmw_ret_t
395 rmw_get_serialized_message_size(
396  const rosidl_message_type_support_t * type_support,
397  const rosidl_message_bounds_t * message_bounds,
398  size_t * size);
399 
401 
419 RMW_PUBLIC
420 RMW_WARN_UNUSED
421 rmw_ret_t
422 rmw_publisher_assert_liveliness(const rmw_publisher_t * publisher);
423 
425 
437 RMW_PUBLIC
438 RMW_WARN_UNUSED
439 rmw_ret_t
440 rmw_serialize(
441  const void * ros_message,
442  const rosidl_message_type_support_t * type_support,
443  rmw_serialized_message_t * serialized_message);
444 
446 
461 RMW_PUBLIC
462 RMW_WARN_UNUSED
463 rmw_ret_t
464 rmw_deserialize(
465  const rmw_serialized_message_t * serialized_message,
466  const rosidl_message_type_support_t * type_support,
467  void * ros_message);
468 
470 
486 RMW_PUBLIC
487 RMW_WARN_UNUSED
488 rmw_ret_t
489 rmw_init_subscription_allocation(
490  const rosidl_message_type_support_t * type_support,
491  const rosidl_message_bounds_t * message_bounds,
492  rmw_subscription_allocation_t * allocation);
493 
495 
503 RMW_PUBLIC
504 RMW_WARN_UNUSED
505 rmw_ret_t
506 rmw_fini_subscription_allocation(
507  rmw_subscription_allocation_t * allocation);
508 
509 RMW_PUBLIC
510 RMW_WARN_UNUSED
511 rmw_subscription_t *
512 rmw_create_subscription(
513  const rmw_node_t * node,
514  const rosidl_message_type_support_t * type_support,
515  const char * topic_name,
516  const rmw_qos_profile_t * qos_policies,
517  bool ignore_local_publications);
518 
519 RMW_PUBLIC
520 RMW_WARN_UNUSED
521 rmw_ret_t
522 rmw_destroy_subscription(rmw_node_t * node, rmw_subscription_t * subscription);
523 
525 
535 RMW_PUBLIC
536 RMW_WARN_UNUSED
537 rmw_ret_t
538 rmw_subscription_count_matched_publishers(
539  const rmw_subscription_t * subscription,
540  size_t * publisher_count);
541 
543 
553 RMW_PUBLIC
554 RMW_WARN_UNUSED
555 rmw_ret_t
556 rmw_take(
557  const rmw_subscription_t * subscription,
558  void * ros_message,
559  bool * taken,
560  rmw_subscription_allocation_t * allocation);
561 
563 
574 RMW_PUBLIC
575 RMW_WARN_UNUSED
576 rmw_ret_t
577 rmw_take_with_info(
578  const rmw_subscription_t * subscription,
579  void * ros_message,
580  bool * taken,
581  rmw_message_info_t * message_info,
582  rmw_subscription_allocation_t * allocation);
583 
585 
601 RMW_PUBLIC
602 RMW_WARN_UNUSED
603 rmw_ret_t
604 rmw_take_serialized_message(
605  const rmw_subscription_t * subscription,
606  rmw_serialized_message_t * serialized_message,
607  bool * taken,
608  rmw_subscription_allocation_t * allocation);
609 
611 
624 RMW_PUBLIC
625 RMW_WARN_UNUSED
626 rmw_ret_t
627 rmw_take_serialized_message_with_info(
628  const rmw_subscription_t * subscription,
629  rmw_serialized_message_t * serialized_message,
630  bool * taken,
631  rmw_message_info_t * message_info,
632  rmw_subscription_allocation_t * allocation);
633 
634 RMW_PUBLIC
635 RMW_WARN_UNUSED
636 rmw_client_t *
637 rmw_create_client(
638  const rmw_node_t * node,
639  const rosidl_service_type_support_t * type_support,
640  const char * service_name,
641  const rmw_qos_profile_t * qos_policies);
642 
643 RMW_PUBLIC
644 RMW_WARN_UNUSED
645 rmw_ret_t
646 rmw_destroy_client(rmw_node_t * node, rmw_client_t * client);
647 
648 RMW_PUBLIC
649 RMW_WARN_UNUSED
650 rmw_ret_t
651 rmw_send_request(
652  const rmw_client_t * client,
653  const void * ros_request,
654  int64_t * sequence_id);
655 
656 RMW_PUBLIC
657 RMW_WARN_UNUSED
658 rmw_ret_t
659 rmw_take_response(
660  const rmw_client_t * client,
661  rmw_request_id_t * request_header,
662  void * ros_response,
663  bool * taken);
664 
665 RMW_PUBLIC
666 RMW_WARN_UNUSED
667 rmw_service_t *
668 rmw_create_service(
669  const rmw_node_t * node,
670  const rosidl_service_type_support_t * type_support,
671  const char * service_name,
672  const rmw_qos_profile_t * qos_policies);
673 
674 RMW_PUBLIC
675 RMW_WARN_UNUSED
676 rmw_ret_t
677 rmw_destroy_service(rmw_node_t * node, rmw_service_t * service);
678 
679 RMW_PUBLIC
680 RMW_WARN_UNUSED
681 rmw_ret_t
682 rmw_take_request(
683  const rmw_service_t * service,
684  rmw_request_id_t * request_header,
685  void * ros_request,
686  bool * taken);
687 
688 RMW_PUBLIC
689 RMW_WARN_UNUSED
690 rmw_ret_t
691 rmw_send_response(
692  const rmw_service_t * service,
693  rmw_request_id_t * request_header,
694  void * ros_response);
695 
696 // TODO(wjwwood): refactor this API to return a return code when updated to use an allocator
698 
722 RMW_PUBLIC
723 RMW_WARN_UNUSED
724 rmw_guard_condition_t *
725 rmw_create_guard_condition(rmw_context_t * context);
726 
727 
729 
735 RMW_PUBLIC
736 RMW_WARN_UNUSED
737 rmw_ret_t
738 rmw_destroy_guard_condition(rmw_guard_condition_t * guard_condition);
739 
740 RMW_PUBLIC
741 RMW_WARN_UNUSED
742 rmw_ret_t
743 rmw_trigger_guard_condition(const rmw_guard_condition_t * guard_condition);
744 
746 
763 RMW_PUBLIC
764 RMW_WARN_UNUSED
765 rmw_wait_set_t *
766 rmw_create_wait_set(rmw_context_t * context, size_t max_conditions);
767 
768 RMW_PUBLIC
769 RMW_WARN_UNUSED
770 rmw_ret_t
771 rmw_destroy_wait_set(rmw_wait_set_t * wait_set);
772 
774 
807 RMW_PUBLIC
808 RMW_WARN_UNUSED
809 rmw_ret_t
810 rmw_wait(
811  rmw_subscriptions_t * subscriptions,
812  rmw_guard_conditions_t * guard_conditions,
813  rmw_services_t * services,
814  rmw_clients_t * clients,
815  rmw_events_t * events,
816  rmw_wait_set_t * wait_set,
817  const rmw_time_t * wait_timeout);
818 
820 
846 RMW_PUBLIC
847 RMW_WARN_UNUSED
848 rmw_ret_t
849 rmw_get_node_names(
850  const rmw_node_t * node,
851  rcutils_string_array_t * node_names,
852  rcutils_string_array_t * node_namespaces);
853 
854 RMW_PUBLIC
855 RMW_WARN_UNUSED
856 rmw_ret_t
857 rmw_count_publishers(
858  const rmw_node_t * node,
859  const char * topic_name,
860  size_t * count);
861 
862 RMW_PUBLIC
863 RMW_WARN_UNUSED
864 rmw_ret_t
865 rmw_count_subscribers(
866  const rmw_node_t * node,
867  const char * topic_name,
868  size_t * count);
869 
870 RMW_PUBLIC
871 RMW_WARN_UNUSED
872 rmw_ret_t
873 rmw_get_gid_for_publisher(const rmw_publisher_t * publisher, rmw_gid_t * gid);
874 
875 RMW_PUBLIC
876 RMW_WARN_UNUSED
877 rmw_ret_t
878 rmw_compare_gids_equal(const rmw_gid_t * gid1, const rmw_gid_t * gid2, bool * result);
879 
881 
907 RMW_PUBLIC
908 RMW_WARN_UNUSED
909 rmw_ret_t
910 rmw_service_server_is_available(
911  const rmw_node_t * node,
912  const rmw_client_t * client,
913  bool * is_available);
914 
915 RMW_PUBLIC
916 RMW_WARN_UNUSED
917 rmw_ret_t
918 rmw_set_log_severity(rmw_log_severity_t severity);
919 
920 #ifdef __cplusplus
921 }
922 #endif
923 
924 #endif // RMW__RMW_H_
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_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.
rmw_set_log_severity
rmw_ret_t rmw_set_log_severity(rmw_log_severity_t severity)
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.
rmw_publish
rmw_ret_t rmw_publish(const rmw_publisher_t *publisher, const void *ros_message, rmw_publisher_allocation_t *allocation)
Publish a given ros_message.
rmw_get_gid_for_publisher
rmw_ret_t rmw_get_gid_for_publisher(const rmw_publisher_t *publisher, rmw_gid_t *gid)
rmw_publisher_assert_liveliness
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) ...
rmw_take_serialized_message
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.
RMW_PUBLIC
#define RMW_PUBLIC
Definition: visibility_control.h:48
rmw_message_info_t
Definition: types.h:268
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.
rmw_services_t
Array of service handles.
Definition: types.h:117
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.
rmw_subscriptions_t
Array of subscriber handles.
Definition: types.h:102
RMW_WARN_UNUSED
#define RMW_WARN_UNUSED
Definition: macros.h:22
rmw_request_id_t
Definition: types.h:170
rmw_trigger_guard_condition
rmw_ret_t rmw_trigger_guard_condition(const rmw_guard_condition_t *guard_condition)
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)
rcutils_uint8_array_t
rmw_destroy_subscription
rmw_ret_t rmw_destroy_subscription(rmw_node_t *node, rmw_subscription_t *subscription)
rmw_publish_serialized_message
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.
rmw_publisher_get_actual_qos
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.
rmw_log_severity_t
enum RMW_PUBLIC_TYPE rmw_log_severity_t
Type mapping of rcutils log severity types to rmw specific types.
rmw_get_implementation_identifier
const char * rmw_get_implementation_identifier(void)
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_subscription_allocation_t
Definition: types.h:89
qos_profiles.h
visibility_control.h
rmw_fini_subscription_allocation
rmw_ret_t rmw_fini_subscription_allocation(rmw_subscription_allocation_t *allocation)
Destroy a publisher allocation object.
rmw_destroy_client
rmw_ret_t rmw_destroy_client(rmw_node_t *node, rmw_client_t *client)
rmw_fini_publisher_allocation
rmw_ret_t rmw_fini_publisher_allocation(rmw_publisher_allocation_t *allocation)
Destroy a publisher allocation object.
rmw_subscription_t
Definition: types.h:55
rmw_context_t
Initialization context structure which is used to store init specific information.
Definition: init.h:37
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_count_subscribers
rmw_ret_t rmw_count_subscribers(const rmw_node_t *node, const char *topic_name, size_t *count)
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_subscription_allocation_t *allocation)
Take an incoming message from a subscription with additional metadata.
rmw_client_t
Definition: types.h:69
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_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.
rmw_count_publishers
rmw_ret_t rmw_count_publishers(const rmw_node_t *node, const char *topic_name, size_t *count)
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.
rmw_destroy_service
rmw_ret_t rmw_destroy_service(rmw_node_t *node, rmw_service_t *service)
rmw_gid_t
Definition: types.h:262
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_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, rmw_subscription_allocation_t *allocation)
Take a message without deserializing it and with its additional message information.
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.
rmw_destroy_wait_set
rmw_ret_t rmw_destroy_wait_set(rmw_wait_set_t *wait_set)
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_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...
rmw_events_t
Definition: types.h:140
rmw_take
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.
rmw_node_assert_liveliness
rmw_ret_t rmw_node_assert_liveliness(const rmw_node_t *node)
Manually assert that this node is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_NODE) ...
rmw_publisher_allocation_t
Definition: types.h:83
rmw_destroy_publisher
rmw_ret_t rmw_destroy_publisher(rmw_node_t *node, rmw_publisher_t *publisher)
rmw_wait_set_t
Definition: types.h:163
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.
rmw_time_t
Definition: types.h:176
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.
rmw_ret_t
int32_t rmw_ret_t
Definition: ret_types.h:25
rmw_get_serialization_format
const char * rmw_get_serialization_format(void)
Get the unique serialization format for this middleware.
rmw_guard_condition_t
Definition: types.h:76
rmw_service_t
Definition: types.h:62
rmw_node_security_options_t
Definition: types.h:188
rmw_guard_conditions_t
Array of guard condition handles.
Definition: types.h:155
rmw_init_publisher_allocation
rmw_ret_t rmw_init_publisher_allocation(const rosidl_message_type_support_t *type_support, const rosidl_message_bounds_t *message_bounds, rmw_publisher_allocation_t *allocation)
Initialize a publisher allocation to be used with later publications.
rmw_publisher_t
Definition: types.h:48
rmw_send_response
rmw_ret_t rmw_send_response(const rmw_service_t *service, rmw_request_id_t *request_header, void *ros_response)
rmw_send_request
rmw_ret_t rmw_send_request(const rmw_client_t *client, const void *ros_request, int64_t *sequence_id)
rmw_clients_t
Array of client handles.
Definition: types.h:132
rmw_get_serialized_message_size
rmw_ret_t rmw_get_serialized_message_size(const rosidl_message_type_support_t *type_support, const rosidl_message_bounds_t *message_bounds, size_t *size)
Compute the size of a serialized message.
rmw_init_subscription_allocation
rmw_ret_t rmw_init_subscription_allocation(const rosidl_message_type_support_t *type_support, const rosidl_message_bounds_t *message_bounds, rmw_subscription_allocation_t *allocation)
Initialize a subscription allocation to be used with later takes.
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.
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.
rmw_compare_gids_equal
rmw_ret_t rmw_compare_gids_equal(const rmw_gid_t *gid1, const rmw_gid_t *gid2, bool *result)
rmw_create_wait_set
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.
rmw_qos_profile_t
ROS MiddleWare quality of service profile.
Definition: types.h:231
rmw_node_t
Definition: types.h:39
rcutils_string_array_t
Generated by   doxygen 1.8.13