[ONME-2844] Avoid option level collisions

To allow a network stack to support both NSAPI and its own options, try to make
sure the NSAPI levels don't collide with level numbers likely to be used by
network stacks.

Distinguish between socket and stack options, and tighten up documentation. Add
IP MRU stack options as an example (implementation not immediately planned for
any stack, but could be useful).

Author: Hasnain Virk

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

@@ -161,30 +161,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
  *