Diff: features/netsocket/nsapi_dns.h

Revision:

1:9db0e321a9f4

Parent:

0:5b88d5760320

--- a/features/netsocket/nsapi_dns.h	Tue Dec 17 23:23:45 2019 +0000
+++ b/features/netsocket/nsapi_dns.h	Tue Dec 31 06:02:27 2019 +0000
@@ -85,8 +85,7 @@
  *  @param addr     Destination for the host address
  *  @param interface_name Network interface name
  *  @param version  IP version to resolve (defaults to NSAPI_IPv4)
- *  @return         0 on success, negative error code on failure
- *                  NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
+ *  @return         See @ref nsapi_dns_query_multiple
  */
 nsapi_error_t nsapi_dns_query(NetworkStack *stack, const char *host,
                               SocketAddress *addr, const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
@@ -156,8 +155,12 @@
  *  @param addr       Array for the host addresses
  *  @param addr_count Number of addresses allocated in the array
  *  @param version    IP version to resolve (defaults to NSAPI_IPv4)
- *  @return           Number of addresses found on success, negative error code on failure
- *                    NSAPI_ERROR_DNS_FAILURE indicates the host could not be found
+ *  @return           Positive number of addresses found on success
+ *  @retval           NSAPI_ERROR_PARAMETER if provided parameters are invalid
+ *  @retval           NSAPI_ERROR_NO_MEMORY if allocation fails due to lack of memory
+ *  @retval           NSAPI_ERROR_DNS_FAILURE if DNS resolution fails
+ *  @retval           NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled and
+ *                    DNS cannot be resolved immediately.
  */
 nsapi_size_or_error_t nsapi_dns_query_multiple(NetworkStack *stack, const char *host,
                                                SocketAddress *addr, nsapi_size_t addr_count,  const char *interface_name, nsapi_version_t version = NSAPI_IPv4);
@@ -216,7 +219,7 @@
   *  @param id       Unique id of the hostname translation operation
   *  @return         0 on success, negative error code on failure
   */
-nsapi_error_t nsapi_dns_query_async_cancel(nsapi_error_t id);
+nsapi_error_t nsapi_dns_query_async_cancel(nsapi_size_or_error_t id);
 
 /** Set a call in callback
  *
@@ -228,6 +231,14 @@
  */
 void nsapi_dns_call_in_set(call_in_callback_cb_t callback);
 
+/**
+ * @brief nsapi_dns_reset Resets all internal states and frees reserved memory, see NOTE!
+ * Can be used to clean up system resources when there is no need for network connections.
+ * NOTE: Does NOT clear asynchronous ongoing operations!
+ * Currently only cleans up DNS cache (if used)
+ */
+void nsapi_dns_reset();
+
 /** Add a domain name server to list of servers to query
  *
  *  @param addr     Destination for the host address