Adding required structs and methods to get a list of publishers or su…

…bscribers with their respective qos (#186)

Signed-off-by: Jaison Titus <jaisontj92@gmail.com>
Signed-off-by: Miaofei <miaofei@amazon.com>

rmw/CMakeLists.txt

@@ -32,10 +32,12 @@ set(rmw_sources
   "src/init_options.c"
   "src/loaned_message_sequence.c"
   "src/names_and_types.c"
+  "src/node_security_options.c"
   "src/publisher_options.c"
   "src/sanity_checks.c"
   "src/subscription_options.c"
-  "src/node_security_options.c"
+  "src/topic_endpoint_info_array.c"
+  "src/topic_endpoint_info.c"
   "src/validate_full_topic_name.c"
   "src/validate_namespace.c"
   "src/validate_node_name.c"

rmw/include/rmw/get_topic_endpoint_info.h

@@ -0,0 +1,128 @@
+// Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef RMW__GET_TOPIC_ENDPOINT_INFO_H_
+#define RMW__GET_TOPIC_ENDPOINT_INFO_H_
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#include "rmw/topic_endpoint_info_array.h"
+#include "rmw/visibility_control.h"
+
+/// Retrieve the information for all publishers to a given topic.
+/**
+ * The retrieved information will contain the publisher's node name, node namespace,
+ * associated topic type, publisher gid and qos profile.
+ *
+ * The node parameter must not be `NULL` and must point to a valid node.
+ *
+ * The topic_name parameter must not be `NULL` and must follow the topic naming rules
+ * mentioned at http://design.ros2.org/articles/topic_and_service_names.html
+ * Names of non-existent topics are allowed.
+ * In that case, this function will return an empty array.
+ *
+ * It is the responsibility of the caller to ensure that `publishers_info` parameter points
+ * to a valid struct of type rmw_topic_endpoint_info_array_t.
+ * The rmw_topic_endpoint_info_array_t struct must be zero initialized.
+ * \see rmw_get_zero_initialized_topic_endpoint_info_array
+ *
+ * The `allocator` will be used to allocate memory to the `info_array` member
+ * inside of `publishers_info`.
+ * Moreover, every `const char *` member inside of
+ * rmw_topic_endpoint_info_t will be assigned a copied value on allocated memory.
+ * \see rmw_topic_endpoint_info_set_topic_type
+ * \see rmw_topic_endpoint_info_set_node_name
+ * \see rmw_topic_endpoint_info_set_node_namespace
+ * However, it is the responsibility of the caller to
+ * reclaim any allocated resources to `publishers_info` to avoid leaking memory.
+ * \see rmw_topic_endpoint_info_array_fini
+ *
+ * \param[in] node the handle to the node being used to query the ROS graph.
+ * \param[in] allocator the allocator to be used when allocating space for the array.
+ * \param[in] topic_name the name of the topic for which the list of publishers will be retrieved.
+ * \param[in] no_mangle if true, the topic name will not be mangled.
+ * \param[out] publishers_info an array of rmw_topic_endpoint_info_t.
+ * \return `RMW_RET_OK` if the query was successful, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if the node is invalid, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
+ * \return `RMW_RET_BAD_ALLOC` if memory allocation fails, or
+ * \return `RMW_RET_ERROR` if an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_get_publishers_info_by_topic(
+  const rmw_node_t * node,
+  rcutils_allocator_t * allocator,
+  const char * topic_name,
+  bool no_mangle,
+  rmw_topic_endpoint_info_array_t * publishers_info);
+
+/// Retrieve the information for all subscriptions to a given topic.
+/**
+ * The retrieved information will contain the subscriptions's node name, node namespace,
+ * associated topic type, subscription gid and qos profile.
+ *
+ * The node parameter must not be `NULL` and must point to a valid node.
+ *
+ * The topic_name parameter must not be `NULL` and must follow the topic naming rules
+ * mentioned at http://design.ros2.org/articles/topic_and_service_names.html
+ * Names of non-existent topics are allowed.
+ * They will return an empty array.
+ *
+ * It is the responsibility of the caller to ensure that `subscriptions_info` parameter points
+ * to a valid struct of type rmw_topic_endpoint_info_array_t.
+ * The rmw_topic_endpoint_info_array_t struct must be zero initialized.
+ * \see rmw_get_zero_initialized_topic_endpoint_info_array
+ *
+ * The `allocator` will be used to allocate memory to the `info_array` member
+ * inside of `publishers_info`.
+ * Moreover, every `const char *` member inside of
+ * rmw_topic_endpoint_info_t will be assigned a copied value on allocated memory.
+ * \see rmw_topic_endpoint_info_set_topic_type
+ * \see rmw_topic_endpoint_info_set_node_name
+ * \see rmw_topic_endpoint_info_set_node_namespace
+ * However, it is the responsibility of the caller to
+ * reclaim any allocated resources to `publishers_info` to avoid leaking memory.
+ * \see rmw_topic_endpoint_info_array_fini
+ *
+ * \param[in] node the handle to the node being used to query the ROS graph.
+ * \param[in] allocator the allocator to be used when allocating space for the array.
+ * \param[in] topic_name the name of the topic for which the list of subscriptions will be retrieved.
+ * \param[in] no_mangle if true, the topic name will not be mangled.
+ * \param[out] subscriptions_info an array of rmw_topic_endpoint_info_t..
+ * \return `RMW_RET_OK` if the query was successful, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if the node is invalid, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
+ * \return `RMW_RET_BAD_ALLOC` if memory allocation fails, or
+ * \return `RMW_RET_ERROR` if an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_get_subscriptions_info_by_topic(
+  const rmw_node_t * node,
+  rcutils_allocator_t * allocator,
+  const char * topic_name,
+  bool no_mangle,
+  rmw_topic_endpoint_info_array_t * subscriptions_info);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RMW__GET_TOPIC_ENDPOINT_INFO_H_

rmw/include/rmw/qos_profiles.h

@@ -100,6 +100,19 @@ static const rmw_qos_profile_t rmw_qos_profile_system_default =
   false
 };
 
+static const rmw_qos_profile_t rmw_qos_profile_unknown =
+{
+  RMW_QOS_POLICY_HISTORY_UNKNOWN,
+  RMW_QOS_POLICY_DEPTH_SYSTEM_DEFAULT,
+  RMW_QOS_POLICY_RELIABILITY_UNKNOWN,
+  RMW_QOS_POLICY_DURABILITY_UNKNOWN,
+  RMW_QOS_DEADLINE_DEFAULT,
+  RMW_QOS_LIFESPAN_DEFAULT,
+  RMW_QOS_POLICY_LIVELINESS_UNKNOWN,
+  RMW_QOS_LIVELINESS_LEASE_DURATION_DEFAULT,
+  false
+};
+
 #ifdef __cplusplus
 }
 #endif

rmw/include/rmw/rmw.h

@@ -55,6 +55,7 @@
  *   - rmw_get_service_names_and_types()
  *   - rmw/names_and_types.h
  *   - rmw/get_topic_names_and_types.h
+ *   - rmw/get_topic_endpoint_info.h
  *   - rmw/get_service_names_and_types.h
  *
  * Further still there are some useful abstractions and utilities:

rmw/include/rmw/topic_endpoint_info.h

@@ -0,0 +1,192 @@
+// Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef RMW__TOPIC_ENDPOINT_INFO_H_
+#define RMW__TOPIC_ENDPOINT_INFO_H_
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#include "rcutils/allocator.h"
+#include "rmw/types.h"
+#include "rmw/visibility_control.h"
+
+/// A structure that encapsulates the name, namespace, topic_type, gid and qos_profile
+/// of publishers and subscriptions for a topic.
+typedef struct RMW_PUBLIC_TYPE rmw_topic_endpoint_info_t
+{
+  /// Name of the node
+  const char * node_name;
+  /// Namespace of the node
+  const char * node_namespace;
+  /// The associated topic type
+  const char * topic_type;
+  /// The endpoint type
+  rmw_endpoint_type_t endpoint_type;
+  /// The GID of the endpoint
+  uint8_t endpoint_gid[RMW_GID_STORAGE_SIZE];
+  /// QoS profile of the endpoint
+  rmw_qos_profile_t qos_profile;
+} rmw_topic_endpoint_info_t;
+
+/// Return a rmw_topic_endpoint_info_t struct with members initialized to `NULL`.
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_topic_endpoint_info_t
+rmw_get_zero_initialized_topic_endpoint_info(void);
+
+/// Finalize a rmw_topic_endpoint_info_t object.
+/**
+ * The rmw_topic_endpoint_info_t struct has members which require memory to be allocated to them before
+ * setting values.
+ * This function reclaims any allocated resources within the object and zeroes out all other
+ * members.
+ *
+ * \param[inout] topic_endpoint_info object to be finalized
+ * \param[in] allocator the allocator used to allocate memory to the object
+ * \returns `RMW_RET_OK` on successfully reclaiming memory, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_fini(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  rcutils_allocator_t * allocator);
+
+/// Set the topic_type in rmw_topic_endpoint_info_t.
+/**
+ * rmw_topic_endpoint_info_t has a member topic_type of type const char *;
+ * this function allocates memory and copies the value of param passed to it.
+ *
+ * \param[inout] topic_endpoint_info pointer to an initialized instance of rmw_topic_endpoint_info_t
+ * \param[in] topic_type the topic_type value to set in rmw_topic_endpoint_info_t
+ * \param[in] allocator the allocator that will be used to allocate memory
+ * \returns `RMW_RET_OK` on successfully setting the topic_type, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_set_topic_type(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  const char * topic_type,
+  rcutils_allocator_t * allocator);
+
+/// Set the node_name in rmw_topic_endpoint_info_t.
+/**
+ * rmw_topic_endpoint_info_t has a member node_name of type const char *;
+ * this function allocates memory and copies the value of param passed to it.
+ *
+ * \param[inout] topic_endpoint_info pointer to an initialized instance of rmw_topic_endpoint_info_t
+ * \param[in] node_name the node_name value to set in rmw_topic_endpoint_info_t
+ * \param[in] allocator the allocator that will be used to allocate memory
+ * \returns `RMW_RET_OK` on successfully setting the node_name, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_set_node_name(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  const char * node_name,
+  rcutils_allocator_t * allocator);
+
+/// Set the node_namespace in rmw_topic_endpoint_info_t.
+/**
+ * rmw_topic_endpoint_info_t has a member node_namespace of type const char *;
+ * this function allocates memory and copies the value of param passed to it.
+ *
+ * \param[inout] topic_endpoint_info pointer to an initialized instance of rmw_topic_endpoint_info_t
+ * \param[in] node_namespace the node_namespace value to set in rmw_topic_endpoint_info_t
+ * \param[in] allocator the allocator that will be used to allocate memory
+ * \returns `RMW_RET_OK` on successfully setting the node_namespace, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_set_node_namespace(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  const char * node_namespace,
+  rcutils_allocator_t * allocator);
+
+/// Set the gid in rmw_topic_endpoint_info_t.
+/**
+ * Copies the values from gid into the gid member inside topic_endpoint_info.
+ *
+ * \param[inout] topic_endpoint_info pointer to an initialized instance of rmw_topic_endpoint_info_t
+ * \param[in] gid the gid value to set in rmw_topic_endpoint_info_t
+ * \param[in] size the size of the gid param
+ * \returns `RMW_RET_OK` on successfully setting the gid, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` size is greater than RMW_GID_STORAGE_SIZE, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_set_endpoint_type(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  rmw_endpoint_type_t type);
+
+/// Set the gid in rmw_topic_endpoint_info_t.
+/**
+ * Copies the values from gid into the gid member inside topic_endpoint_info.
+ *
+ * \param[inout] topic_endpoint_info pointer to an initialized instance of rmw_topic_endpoint_info_t
+ * \param[in] gid the gid value to set in rmw_topic_endpoint_info_t
+ * \param[in] size the size of the gid param
+ * \returns `RMW_RET_OK` on successfully setting the gid, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` size is greater than RMW_GID_STORAGE_SIZE, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_set_gid(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  const uint8_t gid[],
+  size_t size);
+
+/// Set the qos_profile in rmw_topic_endpoint_info_t.
+/**
+ * rmw_topic_endpoint_info_t has a member qos_profile of type const rmw_qos_profile_t *.
+ * This function assigns the passed qos_profile pointer to the member.
+ *
+ * \param[inout] topic_endpoint_info pointer to an initialized instance of rmw_topic_endpoint_info_t
+ * \param[in] qos_profile the qos_profile to set in rmw_topic_endpoint_info_t
+ * \returns `RMW_RET_OK` on successfully setting the qos_profile, or
+ * \returns `RMW_RET_INVALID_ARGUMENT` if any parameters are NULL, or
+ * \returns `RMW_RET_ERROR` when an unspecified error occurs.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_topic_endpoint_info_set_qos_profile(
+  rmw_topic_endpoint_info_t * topic_endpoint_info,
+  const rmw_qos_profile_t * qos_profile);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif    // RMW__TOPIC_ENDPOINT_INFO_H_