locking: Simplify maintenance / debugging /documentation

Update the Public API equivalent of the libcoap functions that need to be
called when locked with a name suffix of _lkd.

Move matching Public API functions out of coap_threadsafe.c to be coded
just ahead of the newly renamed _lkd function.

Properly define the _lkd function in the appropriate _internal.h file for
documentation, removing the #defines from coap_threadsafe_internal.h.

Tag all the Public API functions that have a _lkd function with COAP_API.
COAP_API can then be defined as to what should be done for that function.

Check libcoap library does not call the original Public API function when
it should be calling the _lkd function by marking the Public API not _lkd
functions as deprecated during the libcoap library build.
[Done by the new COAP_API being defined as __attribute__((deprecated)).]

Work in progress for all the functions that need to be multi-thread safe.

include/coap3/coap_dtls_internal.h

@@ -89,7 +89,7 @@ int coap_dtls_context_set_spsk(coap_context_t *coap_context,
  *
  * @param coap_context The CoAP context.
  * @param setup_data A structure containing setup data originally passed into
- *                   coap_new_client_session_psk2().
+ *                   coap_new_client_session_psk2_lkd().
  *
  * @return @c 1 if successful, else @c 0.
  */

include/coap3/coap_net.h

@@ -384,7 +384,7 @@ unsigned int coap_context_get_max_handshake_sessions(const coap_context_t *conte
  *
  * @return        Incremented message id in network byte order.
  */
-uint16_t coap_new_message_id(coap_session_t *session);
+COAP_API uint16_t coap_new_message_id(coap_session_t *session);
 
 /**
  * CoAP stack context must be released with coap_free_context(). This function

include/coap3/coap_net_internal.h

@@ -338,6 +338,19 @@ void coap_cancel_session_messages(coap_context_t *context,
                                   coap_session_t *session,
                                   coap_nack_reason_t reason);
 
+/**
+ * Returns a new message id and updates @p session->tx_mid accordingly. The
+ * message id is returned in network byte order to make it easier to read in
+ * tracing tools.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param session The current coap_session_t object.
+ *
+ * @return        Incremented message id in network byte order.
+ */
+uint16_t coap_new_message_id_lkd(coap_session_t *session);
+
 /**
  * Dispatches the PDUs from the receive queue in given context.
  */

include/coap3/coap_oscore.h

@@ -79,12 +79,12 @@ coap_session_t *coap_new_client_session_oscore(coap_context_t *ctx,
  * @return A new CoAP session or NULL if failed. Call coap_session_release()
  *         to free.
  */
-coap_session_t *coap_new_client_session_oscore_psk(coap_context_t *ctx,
-                                                   const coap_address_t *local_if,
-                                                   const coap_address_t *server,
-                                                   coap_proto_t proto,
-                                                   coap_dtls_cpsk_t *psk_data,
-                                                   coap_oscore_conf_t *oscore_conf);
+COAP_API coap_session_t *coap_new_client_session_oscore_psk(coap_context_t *ctx,
+                                                            const coap_address_t *local_if,
+                                                            const coap_address_t *server,
+                                                            coap_proto_t proto,
+                                                            coap_dtls_cpsk_t *psk_data,
+                                                            coap_oscore_conf_t *oscore_conf);
 
 /**
  * Creates a new client session to the designated server with PKI credentials
@@ -105,12 +105,12 @@ coap_session_t *coap_new_client_session_oscore_psk(coap_context_t *ctx,
  * @return A new CoAP session or NULL if failed. Call coap_session_release()
  *         to free.
  */
-coap_session_t *coap_new_client_session_oscore_pki(coap_context_t *ctx,
-                                                   const coap_address_t *local_if,
-                                                   const coap_address_t *server,
-                                                   coap_proto_t proto,
-                                                   coap_dtls_pki_t *pki_data,
-                                                   coap_oscore_conf_t *oscore_conf);
+COAP_API coap_session_t *coap_new_client_session_oscore_pki(coap_context_t *ctx,
+                                                            const coap_address_t *local_if,
+                                                            const coap_address_t *server,
+                                                            coap_proto_t proto,
+                                                            coap_dtls_pki_t *pki_data,
+                                                            coap_oscore_conf_t *oscore_conf);
 
 /**
  * Set the context's default OSCORE configuration for a server.
@@ -121,8 +121,8 @@ coap_session_t *coap_new_client_session_oscore_pki(coap_context_t *ctx,
  *
  * @return @c 1 if successful, else @c 0.
  */
-int coap_context_oscore_server(coap_context_t *context,
-                               coap_oscore_conf_t *oscore_conf);
+COAP_API int coap_context_oscore_server(coap_context_t *context,
+                                        coap_oscore_conf_t *oscore_conf);
 
 /**
  * Definition of the function used to save the current Sender Sequence Number
@@ -176,8 +176,8 @@ int coap_delete_oscore_conf(coap_oscore_conf_t *oscore_conf);
  *
  * @return @c 1 Successfully added, else @c 0 there is an issue.
  */
-int coap_new_oscore_recipient(coap_context_t *context,
-                              coap_bin_const_t *recipient_id);
+COAP_API int coap_new_oscore_recipient(coap_context_t *context,
+                                       coap_bin_const_t *recipient_id);
 
 /**
  * Release all the information associated for the specific Recipient ID
@@ -190,8 +190,8 @@ int coap_new_oscore_recipient(coap_context_t *context,
  *
  * @return @c 1 Successfully removed, else @c 0 not found.
  */
-int coap_delete_oscore_recipient(coap_context_t *context,
-                                 coap_bin_const_t *recipient_id);
+COAP_API int coap_delete_oscore_recipient(coap_context_t *context,
+                                          coap_bin_const_t *recipient_id);
 
 /** @} */
 

include/coap3/coap_oscore_internal.h

@@ -163,6 +163,133 @@ int coap_rebuild_pdu_for_proxy(coap_pdu_t *pdu);
  */
 int coap_oscore_initiate(coap_session_t *session,
                          coap_oscore_conf_t *oscore_conf);
+/**
+ * Set the context's default OSCORE configuration for a server.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param context     The current coap_context_t object.
+ * @param oscore_conf OSCORE configuration information. This structure is
+ *                    freed off by this call.
+ *
+ * @return @c 1 if successful, else @c 0.
+ */
+int coap_context_oscore_server_lkd(coap_context_t *context,
+                                   coap_oscore_conf_t *oscore_conf);
+
+/**
+ * Release all the information associated for the specific Recipient ID
+ * (and hence and stop any further OSCORE protection for this Recipient).
+ * Note: This is only removed from the OSCORE context as first defined by
+ * coap_new_client_session_oscore*_lkd() or coap_context_oscore_server().
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param context The CoAP  context holding the OSCORE recipient_id to.
+ * @param recipient_id The Recipient ID to remove.
+ *
+ * @return @c 1 Successfully removed, else @c 0 not found.
+ */
+int coap_delete_oscore_recipient_lkd(coap_context_t *context,
+                                     coap_bin_const_t *recipient_id);
+
+/**
+ * Creates a new client session to the designated server, protecting the data
+ * using OSCORE.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context.
+ * @param local_if Address of local interface. It is recommended to use NULL
+ *                 to let the operating system choose a suitable local
+ *                 interface. If an address is specified, the port number
+ *                 should be zero, which means that a free port is
+ *                 automatically selected.
+ * @param server The server's address. If the port number is zero, the default
+ *               port for the protocol will be used.
+ * @param proto  CoAP Protocol.
+ * @param oscore_conf OSCORE configuration information. This structure is
+ *                    freed off by this call.
+ *
+ * @return A new CoAP session or NULL if failed. Call coap_session_release()
+ *         to free.
+ */
+coap_session_t *coap_new_client_session_oscore_lkd(coap_context_t *ctx,
+                                                   const coap_address_t *local_if,
+                                                   const coap_address_t *server,
+                                                   coap_proto_t proto,
+                                                   coap_oscore_conf_t *oscore_conf);
+
+/**
+ * Creates a new client session to the designated server with PKI credentials
+ * as well as protecting the data using OSCORE.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context.
+ * @param local_if Address of local interface. It is recommended to use NULL to
+ *                 let the operating system choose a suitable local interface.
+ *                 If an address is specified, the port number should be zero,
+ *                 which means that a free port is automatically selected.
+ * @param server The server's address. If the port number is zero, the default
+ *               port for the protocol will be used.
+ * @param proto CoAP Protocol.
+ * @param pki_data PKI parameters.
+ * @param oscore_conf OSCORE configuration information. This structure is
+ *                    freed off by this call.
+ *
+ * @return A new CoAP session or NULL if failed. Call coap_session_release()
+ *         to free.
+ */
+coap_session_t *coap_new_client_session_oscore_pki_lkd(coap_context_t *ctx,
+                                                       const coap_address_t *local_if,
+                                                       const coap_address_t *server,
+                                                       coap_proto_t proto,
+                                                       coap_dtls_pki_t *pki_data,
+                                                       coap_oscore_conf_t *oscore_conf);
+
+/**
+ * Creates a new client session to the designated server with PSK credentials
+ * as well as protecting the data using OSCORE.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param ctx The CoAP context.
+ * @param local_if Address of local interface. It is recommended to use NULL to
+ *                 let the operating system choose a suitable local interface.
+ *                 If an address is specified, the port number should be zero,
+ *                 which means that a free port is automatically selected.
+ * @param server The server's address. If the port number is zero, the default
+ *               port for the protocol will be used.
+ * @param proto CoAP Protocol.
+ * @param psk_data PSK parameters.
+ * @param oscore_conf OSCORE configuration information. This structure is
+ *                    freed off by this call.
+ *
+ * @return A new CoAP session or NULL if failed. Call coap_session_release()
+ *         to free.
+ */
+coap_session_t *coap_new_client_session_oscore_psk_lkd(coap_context_t *ctx,
+                                                       const coap_address_t *local_if,
+                                                       const coap_address_t *server,
+                                                       coap_proto_t proto,
+                                                       coap_dtls_cpsk_t *psk_data,
+                                                       coap_oscore_conf_t *oscore_conf);
+
+/**
+ * Add in the specific Recipient ID into the OSCORE context (server only).
+ * Note: This is only added to the OSCORE context as first defined by
+ * coap_new_client_session_oscore*() or coap_context_oscore_server().
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param context The CoAP  context to add the OSCORE recipient_id to.
+ * @param recipient_id The Recipient ID to add.
+ *
+ * @return @c 1 Successfully added, else @c 0 there is an issue.
+ */
+int coap_new_oscore_recipient_lkd(coap_context_t *context,
+                                  coap_bin_const_t *recipient_id);
 
 /** @} */
 

include/coap3/coap_pdu.h

@@ -396,8 +396,8 @@ coap_pdu_t *coap_pdu_init(coap_pdu_type_t type, coap_pdu_code_t code,
  *
  * @return The skeletal PDU or @c NULL if failure.
  */
-coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code,
-                         coap_session_t *session);
+COAP_API coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code,
+                                  coap_session_t *session);
 
 /**
  * Dispose of an CoAP PDU and frees associated storage.

include/coap3/coap_pdu_internal.h

@@ -356,6 +356,21 @@ int coap_update_token(coap_pdu_t *pdu,
  */
 int coap_option_check_repeatable(coap_option_num_t number);
 
+/**
+ * Creates a new CoAP PDU.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param type The type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON,
+ *             COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
+ * @param code The message code of the PDU.
+ * @param session The session that will be using this PDU
+ *
+ * @return The skeletal PDU or @c NULL if failure.
+ */
+coap_pdu_t *coap_new_pdu_lkd(coap_pdu_type_t type, coap_pdu_code_t code,
+                             coap_session_t *session);
+
 /** @} */
 
 #endif /* COAP_COAP_PDU_INTERNAL_H_ */