refactor to remove listener term and document

Signed-off-by: William Woodall <william@osrfoundation.org>

rcl/include/rcl/client.h

@@ -24,12 +24,11 @@ extern "C"
 
 #include "rosidl_runtime_c/service_type_support_struct.h"
 
+#include "rcl/event_callback.h"
 #include "rcl/macros.h"
 #include "rcl/node.h"
 #include "rcl/visibility_control.h"
 
-#include "rmw/listener_callback_type.h"
-
 /// Internal rcl client implementation struct.
 struct rcl_client_impl_t;
 
@@ -411,12 +410,35 @@ RCL_PUBLIC
 bool
 rcl_client_is_valid(const rcl_client_t * client);
 
+/// Set the on new response callback function for the client.
+/**
+ * This API sets the callback function to be called whenever the
+ * client is notified about a new response.
+ *
+ * \sa rmw_client_set_on_new_response_callback for details about this function.
+ *
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | No
+ * Thread-Safe        | Yes
+ * Uses Atomics       | Maybe [1]
+ * Lock-Free          | Maybe [1]
+ * <i>[1] rmw implementation defined</i>
+ *
+ * \param[in] client The client on which to set the callback
+ * \param[in] callback The callback to be called when new responses arrive
+ * \param[in] user_data Given to the callback when called later, may be NULL
+ * \return `RCL_RET_OK` if callback was set to the listener, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if `client` or `callback` is NULL, or
+ * \return `RCL_RET_UNSUPPORTED` if the API is not implemented in the dds implementation
+ */
 RCL_PUBLIC
 RCL_WARN_UNUSED
 rcl_ret_t
-rcl_client_set_listener_callback(
+rcl_client_set_on_new_response_callback(
   const rcl_client_t * client,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data);
 
 #ifdef __cplusplus

rcl/include/rcl/event.h

@@ -23,6 +23,7 @@ extern "C"
 #endif
 
 #include "rcl/client.h"
+#include "rcl/event_callback.h"
 #include "rcl/macros.h"
 #include "rcl/publisher.h"
 #include "rcl/service.h"
@@ -199,12 +200,35 @@ RCL_PUBLIC
 bool
 rcl_event_is_valid(const rcl_event_t * event);
 
+/// Set the callback function for the event.
+/**
+ * This API sets the callback function to be called whenever the
+ * event is notified about a new instance of the event.
+ *
+ * \sa rmw_event_set_callback for more details about this function.
+ *
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | No
+ * Thread-Safe        | Yes
+ * Uses Atomics       | Maybe [1]
+ * Lock-Free          | Maybe [1]
+ * <i>[1] rmw implementation defined</i>
+ *
+ * \param[in] event The event on which to set the callback
+ * \param[in] callback The callback to be called when new events occur
+ * \param[in] user_data Given to the callback when called later, may be NULL
+ * \return `RCL_RET_OK` if callback was set to the listener, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if `event` or `callback` is NULL, or
+ * \return `RCL_RET_UNSUPPORTED` if the API is not implemented in the dds implementation
+ */
 RCL_PUBLIC
 RCL_WARN_UNUSED
 rcl_ret_t
-rcl_event_set_listener_callback(
+rcl_event_set_callback(
   const rcl_event_t * event,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data);
 
 #ifdef __cplusplus

rcl/include/rcl/event_callback.h

@@ -0,0 +1,31 @@
+// Copyright 2021 Open Source Robotics Foundation, Inc.
+//
+// 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 RCL__EVENT_CALLBACK_H_
+#define RCL__EVENT_CALLBACK_H_
+
+#include "rmw/event_callback_type.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+typedef rmw_event_callback_t rcl_event_callback_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RCL__EVENT_CALLBACK_H_

rcl/include/rcl/service.h

@@ -24,12 +24,11 @@ extern "C"
 
 #include "rosidl_runtime_c/service_type_support_struct.h"
 
+#include "rcl/event_callback.h"
 #include "rcl/macros.h"
 #include "rcl/node.h"
 #include "rcl/visibility_control.h"
 
-#include "rmw/listener_callback_type.h"
-
 /// Internal rcl implementation struct.
 struct rcl_service_impl_t;
 
@@ -442,12 +441,35 @@ RCL_PUBLIC
 bool
 rcl_service_is_valid(const rcl_service_t * service);
 
+/// Set the on new request callback function for the service.
+/**
+ * This API sets the callback function to be called whenever the
+ * service is notified about a new request.
+ *
+ * \sa rmw_service_set_on_new_request_callback for details about this function.
+ *
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | No
+ * Thread-Safe        | Yes
+ * Uses Atomics       | Maybe [1]
+ * Lock-Free          | Maybe [1]
+ * <i>[1] rmw implementation defined</i>
+ *
+ * \param[in] service The service on which to set the callback
+ * \param[in] callback The callback to be called when new requests arrive
+ * \param[in] user_data Given to the callback when called later, may be NULL
+ * \return `RCL_RET_OK` if callback was set to the listener, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if `service` or `callback` is NULL, or
+ * \return `RCL_RET_UNSUPPORTED` if the API is not implemented in the dds implementation
+ */
 RCL_PUBLIC
 RCL_WARN_UNUSED
 rcl_ret_t
-rcl_service_set_listener_callback(
+rcl_service_set_on_new_request_callback(
   const rcl_service_t * service,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data);
 
 #ifdef __cplusplus

rcl/include/rcl/subscription.h

@@ -24,11 +24,11 @@ extern "C"
 
 #include "rosidl_runtime_c/message_type_support_struct.h"
 
+#include "rcl/event_callback.h"
 #include "rcl/macros.h"
 #include "rcl/node.h"
 #include "rcl/visibility_control.h"
 
-#include "rmw/listener_callback_type.h"
 #include "rmw/message_sequence.h"
 
 /// Internal rcl implementation struct.
@@ -612,12 +612,36 @@ RCL_PUBLIC
 bool
 rcl_subscription_can_loan_messages(const rcl_subscription_t * subscription);
 
+/// Set the on new message callback function for the subscription.
+/**
+ * This API sets the callback function to be called whenever the
+ * subscription is notified about a new message.
+ *
+ * \sa rmw_subscription_set_on_new_message_callback for details about this
+ * function.
+ *
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | No
+ * Thread-Safe        | Yes
+ * Uses Atomics       | Maybe [1]
+ * Lock-Free          | Maybe [1]
+ * <i>[1] rmw implementation defined</i>
+ *
+ * \param[in] subscription The subscription on which to set the callback
+ * \param[in] callback The callback to be called when new messages arrive
+ * \param[in] user_data Given to the callback when called later, may be NULL
+ * \return `RCL_RET_OK` if successful, or
+ * \return `RCL_RET_INVALID_ARGUMENT` if `subscription` or `callback` is NULL, or
+ * \return `RCL_RET_UNSUPPORTED` if the API is not implemented in the dds implementation
+ */
 RCL_PUBLIC
 RCL_WARN_UNUSED
 rcl_ret_t
-rcl_subscription_set_listener_callback(
+rcl_subscription_set_on_new_message_callback(
   const rcl_subscription_t * subscription,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data);
 
 #ifdef __cplusplus

rcl/src/rcl/client.c

@@ -282,14 +282,19 @@ rcl_client_is_valid(const rcl_client_t * client)
 }
 
 rcl_ret_t
-rcl_client_set_listener_callback(
+rcl_client_set_on_new_response_callback(
   const rcl_client_t * client,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data)
 {
-  return rmw_client_set_listener_callback(
+  if (!rcl_client_is_valid(client)) {
+    // error state already set
+    return RCL_RET_INVALID_ARGUMENT;
+  }
+  RCL_CHECK_FOR_NULL_WITH_MSG(callback, "callback is invalid", return RCL_RET_INVALID_ARGUMENT);
+  return rmw_client_set_on_new_response_callback(
     client->impl->rmw_handle,
-    listener_callback,
+    callback,
     user_data);
 }
 

rcl/src/rcl/event.c

@@ -219,14 +219,19 @@ rcl_event_is_valid(const rcl_event_t * event)
 }
 
 rcl_ret_t
-rcl_event_set_listener_callback(
+rcl_event_set_callback(
   const rcl_event_t * event,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data)
 {
-  return rmw_event_set_listener_callback(
+  if (!rcl_event_is_valid(event)) {
+    // error state already set
+    return RCL_RET_INVALID_ARGUMENT;
+  }
+  RCL_CHECK_FOR_NULL_WITH_MSG(callback, "callback is invalid", return RCL_RET_INVALID_ARGUMENT);
+  return rmw_event_set_callback(
     &event->impl->rmw_handle,
-    listener_callback,
+    callback,
     user_data);
 }
 

rcl/src/rcl/service.c

@@ -302,14 +302,19 @@ rcl_service_is_valid(const rcl_service_t * service)
 }
 
 rcl_ret_t
-rcl_service_set_listener_callback(
+rcl_service_set_on_new_request_callback(
   const rcl_service_t * service,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data)
 {
-  return rmw_service_set_listener_callback(
+  if (!rcl_service_is_valid(service)) {
+    // error state already set
+    return RCL_RET_INVALID_ARGUMENT;
+  }
+  RCL_CHECK_FOR_NULL_WITH_MSG(callback, "callback is invalid", return RCL_RET_INVALID_ARGUMENT);
+  return rmw_service_set_on_new_request_callback(
     service->impl->rmw_handle,
-    listener_callback,
+    callback,
     user_data);
 }
 

rcl/src/rcl/subscription.c

@@ -438,14 +438,19 @@ rcl_subscription_can_loan_messages(const rcl_subscription_t * subscription)
 }
 
 rcl_ret_t
-rcl_subscription_set_listener_callback(
+rcl_subscription_set_on_new_message_callback(
   const rcl_subscription_t * subscription,
-  rmw_listener_callback_t listener_callback,
+  rcl_event_callback_t callback,
   const void * user_data)
 {
-  return rmw_subscription_set_listener_callback(
+  if (!rcl_subscription_is_valid(subscription)) {
+    // error state already set
+    return RCL_RET_INVALID_ARGUMENT;
+  }
+  RCL_CHECK_FOR_NULL_WITH_MSG(callback, "callback is invalid", return RCL_RET_INVALID_ARGUMENT);
+  return rmw_subscription_set_on_new_message_callback(
     subscription->impl->rmw_handle,
-    listener_callback,
+    callback,
     user_data);
 }