Adding host listener functionality

Author: rccarper

include/aws/io/host_resolver.h

@@ -72,6 +72,10 @@ struct aws_host_resolution_config {
     void *impl_data;
 };
 
+struct aws_host_listener;
+
+struct aws_host_listener_options;
+
 /** should you absolutely disdain the default implementation, feel free to implement your own. */
 struct aws_host_resolver_vtable {
     /** clean up everything you allocated, but not resolver itself. */
@@ -95,6 +99,13 @@ struct aws_host_resolver_vtable {
         struct aws_host_resolver *resolver,
         const struct aws_string *host_name,
         uint32_t flags);
+
+    /** creates and adds a listener to the host resolver. */
+    struct aws_host_listener *(
+        *add_host_listener)(struct aws_host_resolver *resolver, const struct aws_host_listener_options *options);
+
+    /** removes a host listener from the host resolver and frees it. */
+    int (*remove_host_listener)(struct aws_host_resolver *resolver, struct aws_host_listener *listener);
 };
 
 struct aws_host_resolver {
@@ -211,6 +222,51 @@ AWS_IO_API size_t aws_host_resolver_get_host_address_count(
     const struct aws_string *host_name,
     uint32_t flags);
 
+/* Callback for receiving new host addresses from a listener. Memory for the new address list is only guaranteed to
+ * exist during the callback, and must be copied if the caller needs it to persist after. */
+typedef void(aws_host_listener_resolved_address_fn)(
+    /* Listener that owns this callback. */
+    struct aws_host_listener *listener,
+
+    /* Array list of aws_host_address structures.  To get an item:
+     *
+     * struct aws_host_address *host_address = NULL;
+     * aws_array_list_get_at_ptr(new_address_list, (void **)&host_address, address_index);
+     * */
+    const struct aws_array_list *new_address_list,
+
+    /* User data that was specified when adding the listener. */
+    void *user_data);
+
+/* Callback for when the listener has completed its clean up. */
+typedef void(aws_host_listener_shutdown_fn)(void *user_data);
+
+struct aws_host_listener_options {
+
+    /* Name of the host to listen for notifications from. */
+    struct aws_byte_cursor host_name;
+
+    /* Callback for when an address is resolved for the specified host. */
+    aws_host_listener_resolved_address_fn *resolved_address_callback;
+
+    /* Callback for when a listener has completely shutdown. */
+    aws_host_listener_shutdown_fn *shutdown_callback;
+
+    /* User data to be passed into each callback. */
+    void *user_data;
+};
+
+/* Create and add a listener to the host resolver using the specified options. */
+AWS_IO_API struct aws_host_listener *aws_host_resolver_add_host_listener(
+    struct aws_host_resolver *resolver,
+    const struct aws_host_listener_options *options);
+
+/* Remove the specified listener from the host resolver, triggering clean up of the listener. Note: this may not happen
+ * synchronously, and it is necessary to wait for the listener's shutdown callback to trigger. */
+AWS_IO_API int aws_host_resolver_remove_host_listener(
+    struct aws_host_resolver *resolver,
+    struct aws_host_listener *listener);
+
 AWS_EXTERN_C_END
 
 #endif /* AWS_IO_HOST_RESOLVER_H */

tests/CMakeLists.txt

@@ -89,6 +89,12 @@ add_test_case(test_resolver_ttls)
 add_test_case(test_resolver_connect_failure_recording)
 add_test_case(test_resolver_ttl_refreshes_on_resolve)
 
+add_test_case(test_resolver_listener_create_destroy)
+add_test_case(test_resolver_add_listener_before_host)
+add_test_case(test_resolver_add_listener_after_host)
+add_test_case(test_resolver_listener_host_re_add_fn)
+add_test_case(test_resolver_listener_multiple_results)
+
 add_test_case(test_pem_single_cert_parse)
 add_test_case(test_pem_private_key_parse)
 add_test_case(test_pem_cert_chain_parse)