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_async.h

@@ -53,9 +53,9 @@ int coap_async_is_supported(void);
  * @return         A pointer to the registered coap_async_t object or @c
  *                 NULL in case of an error.
  */
-coap_async_t *coap_register_async(coap_session_t *session,
-                                  const coap_pdu_t *request,
-                                  coap_tick_t delay);
+COAP_API coap_async_t *coap_register_async(coap_session_t *session,
+                                           const coap_pdu_t *request,
+                                           coap_tick_t delay);
 
 /**
  * Update the delay timeout, so changing when the registered @p async triggers.
@@ -67,7 +67,7 @@ coap_async_t *coap_register_async(coap_session_t *session,
  * @param delay    The amount of time to delay before sending response, 0 means
  *                 wait forever.
  */
-void coap_async_set_delay(coap_async_t *async, coap_tick_t delay);
+COAP_API void coap_async_set_delay(coap_async_t *async, coap_tick_t delay);
 
 /**
  * Trigger the registered @p async.
@@ -77,7 +77,7 @@ void coap_async_set_delay(coap_async_t *async, coap_tick_t delay);
  *
  * @param async The async object to trigger.
  */
-void coap_async_trigger(coap_async_t *async);
+COAP_API void coap_async_trigger(coap_async_t *async);
 
 /**
  * Releases the memory that was allocated by coap_register_async() for the
@@ -99,7 +99,7 @@ void coap_free_async(coap_session_t *session, coap_async_t *async);
  * @return        A pointer to the object identified by @p token or @c NULL if
  *                not found.
  */
-coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t token);
+COAP_API coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t token);
 
 /**
  * Set the application data pointer held in @p async. This overwrites any

include/coap3/coap_async_internal.h

@@ -41,6 +41,30 @@ struct coap_async_t {
   void *appdata;                   /**< User definable data pointer */
 };
 
+/**
+ * Allocates a new coap_async_t object and fills its fields according to
+ * the given @p request. This function returns a pointer to the registered
+ * coap_async_t object or @c NULL on error. Note that this function will
+ * return @c NULL in case that an object with the same identifier is already
+ * registered.
+ *
+ * When the delay expires, a copy of the @p request will get sent to the
+ * appropriate request handler.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param session  The session that is used for asynchronous transmissions.
+ * @param request  The request that is handled asynchronously.
+ * @param delay    The amount of time to delay before sending response, 0 means
+ *                 wait forever.
+ *
+ * @return         A pointer to the registered coap_async_t object or @c
+ *                 NULL in case of an error.
+ */
+coap_async_t *coap_register_async_lkd(coap_session_t *session,
+                                      const coap_pdu_t *request,
+                                      coap_tick_t delay);
+
 /**
  * Checks if there are any pending Async requests - if so, send them off.
  * Otherewise return the time remaining for the next Async to be triggered
@@ -54,6 +78,58 @@ struct coap_async_t {
  */
 coap_tick_t coap_check_async(coap_context_t *context, coap_tick_t now);
 
+/**
+ * Retrieves the object identified by @p token from the list of asynchronous
+ * transactions that are registered with @p context. This function returns a
+ * pointer to that object or @c NULL if not found.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param session The session that is used for asynchronous transmissions.
+ * @param token   The PDU's token of the object to retrieve.
+ *
+ * @return        A pointer to the object identified by @p token or @c NULL if
+ *                not found.
+ */
+coap_async_t *coap_find_async_lkd(coap_session_t *session, coap_bin_const_t token);
+
+/**
+ * Trigger the registered @p async.
+ *
+ * A copy of the original request will get sent to the appropriate request
+ * handler.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param async The async object to trigger.
+ */
+void coap_async_trigger_lkd(coap_async_t *async);
+
+/**
+ * Update the delay timeout, so changing when the registered @p async triggers.
+ *
+ * When the new delay expires, a copy of the original request will get sent to
+ * the appropriate request handler.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param async The object to update.
+ * @param delay    The amount of time to delay before sending response, 0 means
+ *                 wait forever.
+ */
+void coap_async_set_delay_lkd(coap_async_t *async, coap_tick_t delay);
+
+/**
+ * Releases the memory that was allocated by coap_register_async() for the
+ * object @p async.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param session  The session to use.
+ * @param async The object to delete.
+ */
+void coap_free_async_lkd(coap_session_t *session, coap_async_t *async);
+
 /**
  * Removes and frees off all of the async entries for the given context.
  *

include/coap3/coap_block.h

@@ -335,12 +335,12 @@ typedef void (*coap_release_large_data_t)(coap_session_t *session,
  *
  * @return @c 1 if addition is successful, else @c 0.
  */
-int coap_add_data_large_request(coap_session_t *session,
-                                coap_pdu_t *pdu,
-                                size_t length,
-                                const uint8_t *data,
-                                coap_release_large_data_t release_func,
-                                void *app_ptr);
+COAP_API int coap_add_data_large_request(coap_session_t *session,
+                                         coap_pdu_t *pdu,
+                                         size_t length,
+                                         const uint8_t *data,
+                                         coap_release_large_data_t release_func,
+                                         void *app_ptr);
 
 /**
  * Associates given data with the @p response pdu that is passed as fourth
@@ -392,18 +392,18 @@ int coap_add_data_large_request(coap_session_t *session,
  *
  * @return @c 1 if addition is successful, else @c 0.
  */
-int coap_add_data_large_response(coap_resource_t *resource,
-                                 coap_session_t *session,
-                                 const coap_pdu_t *request,
-                                 coap_pdu_t *response,
-                                 const coap_string_t *query,
-                                 uint16_t media_type,
-                                 int maxage,
-                                 uint64_t etag,
-                                 size_t length,
-                                 const uint8_t *data,
-                                 coap_release_large_data_t release_func,
-                                 void *app_ptr);
+COAP_API int coap_add_data_large_response(coap_resource_t *resource,
+                                          coap_session_t *session,
+                                          const coap_pdu_t *request,
+                                          coap_pdu_t *response,
+                                          const coap_string_t *query,
+                                          uint16_t media_type,
+                                          int maxage,
+                                          uint64_t etag,
+                                          size_t length,
+                                          const uint8_t *data,
+                                          coap_release_large_data_t release_func,
+                                          void *app_ptr);
 
 /**
  * Set the context level CoAP block handling bits for handling RFC7959.

include/coap3/coap_block_internal.h

@@ -305,6 +305,72 @@ coap_lg_xmit_t *coap_find_lg_xmit_response(const coap_session_t *session,
                                            const coap_pdu_t *request,
                                            const coap_resource_t *resource,
                                            const coap_string_t *query);
+
+/**
+ * Associates given data with the @p response pdu that is passed as fourth
+ * parameter.
+ *
+ * This function will fail if data has already been added to the @p pdu.
+ *
+ * If all the data can be transmitted in a single PDU, this is functionally
+ * the same as coap_add_data() except @p release_func (if not NULL) will get
+ * invoked after data transmission. The Content-Format, Max-Age and ETag
+ * options may be added in as appropriate.
+ *
+ * Used by a server request handler to create the response.
+ *
+ * If the data spans multiple PDUs, then the data will get transmitted using
+ * (Q-)Block2 (response) option with the addition of the Size2 and ETag
+ * options. The underlying library will handle the transmission of the
+ * individual blocks. Once the body of data has been transmitted (or a
+ * failure occurred), then @p release_func (if not NULL) will get called so the
+ * application can de-allocate the @p data based on @p app_data. It is the
+ * responsibility of the application not to change the contents of @p data
+ * until the data transfer has completed.
+ *
+ * There is no need for the application to include the (Q-)Block2 option in the
+ * @p pdu.
+ *
+ * coap_add_data_large_response_lkd() (or the alternative coap_add_data_large_*()
+ * functions) must be called only once per PDU and must be the last PDU update
+ * before returning from the request handler function.
+ *
+ * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
+ * for libcoap to work correctly when using this function.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param resource   The resource the data is associated with.
+ * @param session    The coap session.
+ * @param request    The requesting pdu.
+ * @param response   The response pdu.
+ * @param query      The query taken from the (original) requesting pdu.
+ * @param media_type The content format of the data.
+ * @param maxage     The maxmimum life of the data. If @c -1, then there
+ *                   is no maxage.
+ * @param etag       ETag to use if not 0.
+ * @param length     The total length of the data.
+ * @param data       The entire data block to transmit.
+ * @param release_func The function to call to de-allocate @p data or NULL if
+ *                   the function is not required.
+ * @param app_ptr    A Pointer that the application can provide for when
+ *                   release_func() is called.
+ *
+ * @return @c 1 if addition is successful, else @c 0.
+ */
+int coap_add_data_large_response_lkd(coap_resource_t *resource,
+                                     coap_session_t *session,
+                                     const coap_pdu_t *request,
+                                     coap_pdu_t *response,
+                                     const coap_string_t *query,
+                                     uint16_t media_type,
+                                     int maxage,
+                                     uint64_t etag,
+                                     size_t length,
+                                     const uint8_t *data,
+                                     coap_release_large_data_t release_func,
+                                     void *app_ptr);
+
 #endif /* COAP_SERVER_SUPPORT */
 
 #if COAP_CLIENT_SUPPORT
@@ -339,7 +405,7 @@ int coap_block_drop_resp_q_block2_crcv(coap_session_t *session,
 
 /**
  * The function checks that the code in a newly formed lg_xmit created by
- * coap_add_data_large_response() is updated.
+ * coap_add_data_large_response_lkd() is updated.
  *
  * @param session  The session.
  * @param request  The request PDU to to check.
@@ -354,6 +420,57 @@ void coap_check_code_lg_xmit(const coap_session_t *session,
                              const coap_string_t *query);
 
 #if COAP_CLIENT_SUPPORT
+/**
+ * Associates given data with the @p pdu that is passed as second parameter.
+ *
+ * This function will fail if data has already been added to the @p pdu.
+ *
+ * If all the data can be transmitted in a single PDU, this is functionally
+ * the same as coap_add_data_lkd() except @p release_func (if not NULL) will get
+ * invoked after data transmission.
+ *
+ * Used for a client request.
+ *
+ * If the data spans multiple PDUs, then the data will get transmitted using
+ * (Q-)Block1 option with the addition of the Size1 and Request-Tag options.
+ * The underlying library will handle the transmission of the individual blocks.
+ * Once the body of data has been transmitted (or a failure occurred), then
+ * @p release_func (if not NULL) will get called so the application can
+ * de-allocate the @p data based on @p app_data. It is the responsibility of
+ * the application not to change the contents of @p data until the data
+ * transfer has completed.
+ *
+ * There is no need for the application to include the (Q-)Block1 option in the
+ * @p pdu.
+ *
+ * coap_add_data_large_request_lkd() (or the alternative coap_add_data_large_*()
+ * functions) must be called only once per PDU and must be the last PDU update
+ * before the PDU is transmitted. The (potentially) initial data will get
+ * transmitted when coap_send() is invoked.
+ *
+ * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
+ * for libcoap to work correctly when using this function.
+ *
+ * Note: This function must be called in the locked state.
+ *
+ * @param session  The session to associate the data with.
+ * @param pdu      The PDU to associate the data with.
+ * @param length   The length of data to transmit.
+ * @param data     The data to transmit.
+ * @param release_func The function to call to de-allocate @p data or @c NULL
+ *                 if the function is not required.
+ * @param app_ptr  A Pointer that the application can provide for when
+ *                 release_func() is called.
+ *
+ * @return @c 1 if addition is successful, else @c 0.
+ */
+int coap_add_data_large_request_lkd(coap_session_t *session,
+                                    coap_pdu_t *pdu,
+                                    size_t length,
+                                    const uint8_t *data,
+                                    coap_release_large_data_t release_func,
+                                    void *app_ptr);
+
 /**
  * The function checks if the token needs to be updated before PDU is
  * presented to the application (only relevant to clients).

include/coap3/coap_cache.h

@@ -123,8 +123,8 @@ void coap_delete_cache_key(coap_cache_key_t *cache_key);
  *
  * @return          @return @c 1 if successful, else @c 0.
  */
-int coap_cache_ignore_options(coap_context_t *context,
-                              const uint16_t *options, size_t count);
+COAP_API int coap_cache_ignore_options(coap_context_t *context,
+                                       const uint16_t *options, size_t count);
 
 /**
  * Create a new cache-entry hash keyed by cache-key derived from the PDU.
@@ -149,11 +149,11 @@ int coap_cache_ignore_options(coap_context_t *context,
  *
  * @return          The returned cache-key or @c NULL if failure.
  */
-coap_cache_entry_t *coap_new_cache_entry(coap_session_t *session,
-                                         const coap_pdu_t *pdu,
-                                         coap_cache_record_pdu_t record_pdu,
-                                         coap_cache_session_based_t session_based,
-                                         unsigned int idle_time);
+COAP_API coap_cache_entry_t *coap_new_cache_entry(coap_session_t *session,
+                                                  const coap_pdu_t *pdu,
+                                                  coap_cache_record_pdu_t record_pdu,
+                                                  coap_cache_session_based_t session_based,
+                                                  unsigned int idle_time);
 
 /**
  * Remove a cache-entry from the hash list and free off all the appropriate
@@ -175,8 +175,8 @@ void coap_delete_cache_entry(coap_context_t *context,
  *
  * @return The cache-entry for @p cache_key or @c NULL if not found.
  */
-coap_cache_entry_t *coap_cache_get_by_key(coap_context_t *context,
-                                          const coap_cache_key_t *cache_key);
+COAP_API coap_cache_entry_t *coap_cache_get_by_key(coap_context_t *context,
+                                                   const coap_cache_key_t *cache_key);
 
 /**
  * Searches for a cache-entry corresponding to @p pdu. This
@@ -190,9 +190,9 @@ coap_cache_entry_t *coap_cache_get_by_key(coap_context_t *context,
  *
  * @return The cache-entry for @p request or @c NULL if not found.
  */
-coap_cache_entry_t *coap_cache_get_by_pdu(coap_session_t *session,
-                                          const coap_pdu_t *pdu,
-                                          coap_cache_session_based_t session_based);
+COAP_API coap_cache_entry_t *coap_cache_get_by_pdu(coap_session_t *session,
+                                                   const coap_pdu_t *pdu,
+                                                   coap_cache_session_based_t session_based);
 
 /**
  * Returns the PDU information stored in the @p coap_cache entry.