From 5837e3771ef064a59b67180f453aa77930348cf9 Mon Sep 17 00:00:00 2001 From: paul-szczepanek-arm <33840200+paul-szczepanek-arm@users.noreply.github.com> Date: Wed, 24 Oct 2018 20:35:53 +0100 Subject: [PATCH] return codes --- features/netsocket/DNS.h | 38 +++++++++++++-------------- features/netsocket/NetworkInterface.h | 20 +++++++------- features/netsocket/NetworkStack.h | 34 ++++++++++++------------ 3 files changed, 46 insertions(+), 46 deletions(-) diff --git a/features/netsocket/DNS.h b/features/netsocket/DNS.h index 9e74744b6b..2bed8c26dc 100644 --- a/features/netsocket/DNS.h +++ b/features/netsocket/DNS.h @@ -20,7 +20,7 @@ class DNS { public: - /** Translates a hostname to an IP address with specific version + /** Translate a hostname to an IP address with specific version. * * The hostname may be either a domain name or an IP address. If the * hostname is an IP address, no network transactions will be performed. @@ -28,16 +28,16 @@ public: * If no stack-specific DNS resolution is provided, the hostname * will be resolve using a UDP socket on the stack. * - * @param host Hostname to resolve - * @param address Destination for the host SocketAddress + * @param host Hostname to resolve. + * @param address Pointer to a SocketAddress to store the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates - * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on success, negative error code on failure + * version is chosen by the stack (defaults to NSAPI_UNSPEC). + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0; - /** Hostname translation callback (asynchronous) + /** Hostname translation callback for gethostbyname_async. * * Callback will be called after DNS resolution completes or a failure occurs. * @@ -47,12 +47,12 @@ public: * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param status 0 on success, negative error code on failure - * @param address On success, destination for the host SocketAddress + * @param result NSAPI_ERROR_OK on success, negative error code on failure. + * @param address On success, destination for the host SocketAddress. */ typedef mbed::Callback hostbyname_cb_t; - /** Translates a hostname to an IP address (asynchronous) + /** Translate a hostname to an IP address (asynchronous) * * The hostname may be either a domain name or an IP address. If the * hostname is an IP address, no network transactions will be performed. @@ -65,31 +65,31 @@ public: * is success (IP address was found from DNS cache), callback will be called * before function returns. * - * @param host Hostname to resolve - * @param callback Callback that is called for result + * @param host Hostname to resolve. + * @param callback Callback that is called to return the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates - * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on immediate success, + * version is chosen by the stack (defaults to NSAPI_UNSPEC). + * @return NSAPI_ERROR_OK on immediate success, * negative error code on immediate failure or * a positive unique id that represents the hostname translation operation - * and can be passed to cancel + * and can be passed to cancel. */ virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC) = 0; - /** Cancels asynchronous hostname translation + /** Cancel asynchronous hostname translation. * * When translation is cancelled, callback will not be called. * - * @param id Unique id of the hostname translation operation - * @return 0 on success, negative error code on failure + * @param id Unique id of the hostname translation operation returned by gethostbyname_async. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0; /** Add a domain name server to list of servers to query * - * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @param address DNS server host address. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0; }; diff --git a/features/netsocket/NetworkInterface.h b/features/netsocket/NetworkInterface.h index 524a67b0ed..2c357a57a1 100644 --- a/features/netsocket/NetworkInterface.h +++ b/features/netsocket/NetworkInterface.h @@ -118,7 +118,7 @@ public: * @param ip_address Null-terminated representation of the local IP address * @param netmask Null-terminated representation of the local network mask * @param gateway Null-terminated representation of the local gateway - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway); @@ -128,19 +128,19 @@ public: * that the network is disconnected. * * @param dhcp True to enable DHCP. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t set_dhcp(bool dhcp); /** Start the interface. * - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t connect() = 0; /** Stop the interface. * - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t disconnect() = 0; @@ -153,10 +153,10 @@ public: * will be resolve using a UDP socket on the stack. * * @param host Hostname to resolve. - * @param address Destination for the host SocketAddress. + * @param address Pointer to a SocketAddress to store the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates * version is chosen by the stack (defaults to NSAPI_UNSPEC). - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); @@ -171,7 +171,7 @@ public: * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param result 0 on success, negative error code on failure. + * @param result NSAPI_ERROR_OK on success, negative error code on failure. * @param address On success, destination for the host SocketAddress. */ typedef mbed::Callback hostbyname_cb_t; @@ -207,14 +207,14 @@ public: * * @param id Unique id of the hostname translation operation (returned * by gethostbyname_async) - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t gethostbyname_async_cancel(int id); /** Add a domain name server to list of servers to query * * @param address Address for the dns host. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t add_dns_server(const SocketAddress &address); @@ -237,7 +237,7 @@ public: /** Set blocking status of connect() which by default should be blocking. * * @param blocking Use true to make connect() blocking. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t set_blocking(bool blocking); diff --git a/features/netsocket/NetworkStack.h b/features/netsocket/NetworkStack.h index 2ea7757dca..945b8d53d4 100644 --- a/features/netsocket/NetworkStack.h +++ b/features/netsocket/NetworkStack.h @@ -54,10 +54,10 @@ public: * will be resolve using a UDP socket on the stack. * * @param host Hostname to resolve - * @param address Destination for the host SocketAddress + * @param address Pointer to a SocketAddress to store the result. * @param version IP version of address to resolve, NSAPI_UNSPEC indicates * version is chosen by the stack (defaults to NSAPI_UNSPEC) - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); @@ -72,7 +72,7 @@ public: * The callback should not perform expensive operations such as socket recv/send * calls or blocking operations. * - * @param status 0 on success, negative error code on failure + * @param status NSAPI_ERROR_OK on success, negative error code on failure * @param address On success, destination for the host SocketAddress */ typedef mbed::Callback hostbyname_cb_t; @@ -107,14 +107,14 @@ public: * When translation is cancelled, callback will not be called. * * @param id Unique id of the hostname translation operation - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t gethostbyname_async_cancel(int id); /** Add a domain name server to list of servers to query * * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t add_dns_server(const SocketAddress &address); @@ -125,7 +125,7 @@ public: * * @param index Index of the DNS server, starts from zero * @param address Destination for the host address - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t get_dns_server(int index, SocketAddress *address); @@ -142,7 +142,7 @@ public: * @param optname Level-specific option name * @param optval Option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen); @@ -156,7 +156,7 @@ public: * @param optname Level-specific option name * @param optval Destination for option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen); @@ -182,7 +182,7 @@ protected: * * @param handle Destination for the handle to a newly created socket * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0; @@ -192,7 +192,7 @@ protected: * with the socket. * * @param handle Socket handle - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0; @@ -203,7 +203,7 @@ protected: * * @param handle Socket handle * @param address Local address to bind - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. */ virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0; @@ -215,7 +215,7 @@ protected: * @param handle Socket handle * @param backlog Number of pending connections that can be queued * simultaneously - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0; @@ -226,7 +226,7 @@ protected: * * @param handle Socket handle * @param address The SocketAddress of the remote host - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0; @@ -246,7 +246,7 @@ protected: * @param server Socket handle to server to accept from * @param handle Destination for a handle to the newly created socket * @param address Destination for the remote address or NULL - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t socket_accept(nsapi_socket_t server, nsapi_socket_t *handle, SocketAddress *address = 0) = 0; @@ -347,7 +347,7 @@ protected: * @param optname Stack-specific option identifier * @param optval Option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen); @@ -363,7 +363,7 @@ protected: * @param optname Stack-specific option identifier * @param optval Destination for option value * @param optlen Length of the option value - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen); @@ -397,7 +397,7 @@ private: * * @param delay Delay in milliseconds * @param func Callback to be called - * @return 0 on success, negative error code on failure + * @return NSAPI_ERROR_OK on success, negative error code on failure */ virtual nsapi_error_t call_in(int delay, mbed::Callback func); };