Merge pull request #3458 from hasnainvirk/nsapi_levels

[ONME-2844] Avoid option level collisions

Author: 0xc0170

features/netsocket/NetworkStack.h

@@ -68,28 +68,31 @@ class NetworkStack
      */
     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
 
-    /*  Set stack-specific stack options
+    /*  Set stack options
      *
-     *  The setstackopt allow an application to pass stack-specific hints
-     *  to the underlying stack. For unsupported options,
-     *  NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified.
+     *  setstackopt allows an application to pass stack-specific options
+     *  to the underlying stack using stack-specific level and option names,
+     *  or to request generic options using levels from nsapi_stack_level_t.
      *
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
+     *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
+     *  and the stack is unmodified.
+     *
+     *  @param level    Stack-specific protocol level or nsapi_stack_level_t
+     *  @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
      */
     virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
 
-    /*  Get stack-specific stack options
+    /*  Get stack options
      *
-     *  The getstackopt allow an application to retrieve stack-specific hints
-     *  from the underlying stack. For unsupported options,
-     *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
+     *  getstackopt allows an application to retrieve stack-specific options
+     *  to the underlying stack using stack-specific level and option names,
+     *  or to request generic options using levels from nsapi_stack_level_t.
      *
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
+     *  @param level    Stack-specific protocol level or nsapi_stack_level_t
+     *  @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

features/netsocket/Socket.h

@@ -120,28 +120,34 @@ class Socket {
      */
     void set_timeout(int timeout);
 
-    /*  Set stack-specific socket options
+    /*  Set socket options
      *
-     *  The setsockopt allow an application to pass stack-specific hints
-     *  to the underlying stack. For unsupported options,
-     *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
+     *  setsockopt allows an application to pass stack-specific options
+     *  to the underlying stack using stack-specific level and option names,
+     *  or to request generic options using levels from nsapi_socket_level_t.
      *
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
+     *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
+     *  and the socket is unmodified.
+     *
+     *  @param level    Stack-specific protocol level or nsapi_socket_level_t
+     *  @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
      */    
     nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
 
-    /*  Get stack-specific socket options
+    /*  Get socket options
+     *
+     *  getsockopt allows an application to retrieve stack-specific options
+     *  from the underlying stack using stack-specific level and option names,
+     *  or to request generic options using levels from nsapi_socket_level_t.
      *
-     *  The getstackopt allow an application to retrieve stack-specific hints
-     *  from the underlying stack. For unsupported options,
-     *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
+     *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
+     *  and the socket is unmodified.
      *
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
+     *  @param level    Stack-specific protocol level or nsapi_socket_level_t
+     *  @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

features/netsocket/nsapi_types.h

@@ -164,30 +164,57 @@ typedef enum nsapi_protocol {
 } nsapi_protocol_t;
 
 /*  Enum of standardized stack option levels
+ *  for use with NetworkStack::setstackopt and getstackopt.
  *
- *  @enum nsapi_level_t
+ *  @enum nsapi_stack_level_t
  */
-typedef enum nsapi_level {
-    NSAPI_STACK,  /*!< Stack option level */
-    NSAPI_SOCKET, /*!< Socket option level */
-} nsapi_level_t;
+typedef enum nsapi_stack_level {
+    NSAPI_STACK     = 5000, /*!< Stack option level - see nsapi_stack_option_t for options */
+} nsapi_stack_level_t;
 
-/*  Enum of standardized stack options
+/*  Enum of standardized stack option names for level NSAPI_STACK
+ *  of NetworkStack::setstackopt and getstackopt.
  *
  *  These options may not be supported on all stacks, in which
- *  case NSAPI_ERROR_UNSUPPORTED may be returned from setsockopt.
+ *  case NSAPI_ERROR_UNSUPPORTED may be returned.
  *
- *  @enum nsapi_option_t
+ *  @enum nsapi_stack_option_t
  */
-typedef enum nsapi_option {
+typedef enum nsapi_stack_option {
+    NSAPI_IPV4_MRU, /*!< Sets/gets size of largest IPv4 fragmented datagram to reassemble */
+    NSAPI_IPV6_MRU, /*!< Sets/gets size of largest IPv6 fragmented datagram to reassemble */
+} nsapi_stack_option_t;
+
+/*  Enum of standardized socket option levels
+ *  for use with Socket::setsockopt and getsockopt.
+ *
+ *  @enum nsapi_socket_level_t
+ */
+typedef enum nsapi_socket_level {
+    NSAPI_SOCKET    = 7000, /*!< Socket option level - see nsapi_socket_option_t for options */
+} nsapi_socket_level_t;
+
+/*  Enum of standardized socket option names for level NSAPI_SOCKET
+ *  of Socket::setsockopt and getsockopt.
+ *
+ *  These options may not be supported on all stacks, in which
+ *  case NSAPI_ERROR_UNSUPPORTED may be returned.
+ *
+ *  @enum nsapi_socket_option_t
+ */
+typedef enum nsapi_socket_option {
     NSAPI_REUSEADDR, /*!< Allow bind to reuse local addresses */
     NSAPI_KEEPALIVE, /*!< Enables sending of keepalive messages */
     NSAPI_KEEPIDLE,  /*!< Sets timeout value to initiate keepalive */
     NSAPI_KEEPINTVL, /*!< Sets timeout value for keepalive */
     NSAPI_LINGER,    /*!< Keeps close from returning until queues empty */
     NSAPI_SNDBUF,    /*!< Sets send buffer size */
     NSAPI_RCVBUF,    /*!< Sets recv buffer size */
-} nsapi_option_t;
+} nsapi_socket_option_t;
+
+/* Backwards compatibility - previously didn't distinguish stack and socket options */
+typedef nsapi_socket_level_t nsapi_level_t;
+typedef nsapi_socket_option_t nsapi_option_t;
 
 /** nsapi_wifi_ap structure
  *