diff --git a/doc/upgrade_4.2.1_4.3.0.txt b/doc/upgrade_4.2.1_4.3.0.txt index c1cd5cbf..d87e7ff7 100644 --- a/doc/upgrade_4.2.1_4.3.0.txt +++ b/doc/upgrade_4.2.1_4.3.0.txt @@ -351,8 +351,7 @@ Splitting up large data transmission into blocks (RFC7959) can now all be handled by internally by libcoap, removing the need for applications to know anything about how to work with blocks, or need to do any block packet loss recovery. In simple terms, `coap_context_set_block_mode()` must be called, -`coap_send_large()` used instead of `coap_send()`, `coap_add_data()` (or -`coap_add_data_blocked_response()`) is replaced by +`coap_add_data()` (or `coap_add_data_blocked_response()`) is replaced by `coap_add_data_large_response()` or `coap_add_data_large_request()`, and `coap_get_data_large()` used instead of `coap_get_data()`. See man page `coap_block(3)` for further information. @@ -363,7 +362,7 @@ There are 3 ways of handling the block transfers This is how things were done in 4.2.1. The application recognizes the next block request coming in and then generates the next block response (including -setting up the PDU if client). To continue this, +setting up the PDU if client). To continue using this method, `coap_context_set_block_mode()` must not be called and none of the `_large` functions used. @@ -408,8 +407,8 @@ second time in the call-back handler will throw up a Informational warning. For the client, there is a new function `coap_cancel_observe()` that can be called to cancel an observation on the server. To use it, -`coap_context_set_block_mode()` has to be called and `coap_send_large()` has to -be used to send the initial request containing the Observe option. +`coap_context_set_block_mode()` has to be called prior to sending the initial +request containing the Observe option. == Unused function parameters diff --git a/examples/coap-client.c b/examples/coap-client.c index 9526999e..1e86d5a7 100644 --- a/examples/coap-client.c +++ b/examples/coap-client.c @@ -305,7 +305,7 @@ nack_handler(coap_session_t *session COAP_UNUSED, } /* - * Response handler used for coap_send_large() responses + * Response handler used for coap_send() responses */ static coap_response_t message_handler(coap_session_t *session COAP_UNUSED, @@ -1675,7 +1675,7 @@ main(int argc, char **argv) { if (coap_get_log_level() < LOG_DEBUG) coap_show_pdu(LOG_INFO, pdu); - coap_send_large(session, pdu); + coap_send(session, pdu); wait_ms = wait_seconds * 1000; coap_log(LOG_DEBUG, "timeout is set to %u seconds\n", wait_seconds); diff --git a/examples/coap-server.c b/examples/coap-server.c index 9bcf3a21..8bc5671b 100644 --- a/examples/coap-server.c +++ b/examples/coap-server.c @@ -857,7 +857,7 @@ remove_proxy_association(coap_session_t *session, int send_failure) { "Cannot add token to incoming proxy response PDU\n"); } - if (coap_send_large(proxy_list[i].incoming, response) == + if (coap_send(proxy_list[i].incoming, response) == COAP_INVALID_MID) { coap_log(LOG_INFO, "Failed to send PDU with 5.02 gateway issue\n"); } @@ -1204,7 +1204,7 @@ hnd_proxy_uri(coap_resource_t *resource COAP_UNUSED, if (coap_get_log_level() < LOG_DEBUG) coap_show_pdu(LOG_INFO, pdu); - coap_send_large(ongoing, pdu); + coap_send(ongoing, pdu); goto cleanup; } else { @@ -1707,7 +1707,7 @@ proxy_message_handler(coap_session_t *session, if (coap_get_log_level() < LOG_DEBUG) coap_show_pdu(LOG_INFO, pdu); - coap_send_large(incoming, pdu); + coap_send(incoming, pdu); return COAP_RESPONSE_OK; } diff --git a/include/coap3/block.h b/include/coap3/block.h index 188129cc..148deb0a 100644 --- a/include/coap3/block.h +++ b/include/coap3/block.h @@ -219,7 +219,7 @@ typedef void (*coap_release_large_data_t)(coap_session_t *session, * coap_add_data_large_request() (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() or preferably coap_send_large() is invoked. + * 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. @@ -326,8 +326,8 @@ void coap_context_set_block_mode(coap_context_t *context, uint8_t block_mode); /** - * Cancel an observe that is being tracked by the client large receive logic - * when using coap_send_large(). + * Cancel an observe that is being tracked by the client large receive logic. + * (coap_context_set_block_mode() has to be called) * This will trigger the sending of an observe cancel pdu to the server. * * @param session The session that is being used for the observe. diff --git a/include/coap3/coap_net_internal.h b/include/coap3/coap_net_internal.h index d7cbb37e..2c06613f 100644 --- a/include/coap3/coap_net_internal.h +++ b/include/coap3/coap_net_internal.h @@ -341,6 +341,23 @@ coap_pdu_t *coap_wellknown_response(coap_context_t *context, */ unsigned int coap_calc_timeout(coap_session_t *session, unsigned char r); +/** + * Sends a CoAP message to given peer. The memory that is + * allocated for the pdu will be released by coap_send_internal(). + * The caller must not use the pdu after calling coap_send_internal(). + * + * If the response body is split into multiple payloads using blocks, libcoap + * will handle asking for the subsequent blocks and any necessary recovery + * needed. + * + * @param session The CoAP session. + * @param pdu The CoAP PDU to send. + * + * @return The message id of the sent message or @c + * COAP_INVALID_MID on error. + */ +coap_mid_t coap_send_internal(coap_session_t *session, coap_pdu_t *pdu); + /** @} */ #endif /* COAP_NET_INTERNAL_H_ */ diff --git a/include/coap3/net.h b/include/coap3/net.h index f3977756..64ef26b2 100644 --- a/include/coap3/net.h +++ b/include/coap3/net.h @@ -464,22 +464,7 @@ coap_send_rst(coap_session_t *session, const coap_pdu_t *request) { */ coap_mid_t coap_send( coap_session_t *session, coap_pdu_t *pdu ); -/** - * Sends a CoAP message to given peer. The memory that is - * allocated for the pdu will be released by coap_send_large(). - * The caller must not use the pdu after calling coap_send_large(). - * - * If the response body is split into multiple payloads using blocks, libcoap - * will handle asking for the subsequent blocks and any necessary recovery - * needed. - * - * @param session The CoAP session. - * @param pdu The CoAP PDU to send. - * - * @return The message id of the sent message or @c - * COAP_INVALID_MID on error. - */ -coap_mid_t coap_send_large(coap_session_t *session, coap_pdu_t *pdu); +#define coap_send_large(session, pdu) coap_send(session, pdu) /** * Invokes the event handler of @p context for the given @p event and diff --git a/include/coap3/pdu.h b/include/coap3/pdu.h index 0cb34568..b0c4e78f 100644 --- a/include/coap3/pdu.h +++ b/include/coap3/pdu.h @@ -337,8 +337,8 @@ typedef enum coap_pdu_code_t { * Creates a new CoAP PDU with at least enough storage space for the given * @p size maximum message size. The function returns a pointer to the * node coap_pdu_t object on success, or @c NULL on error. The storage allocated - * for the result must be released with coap_delete_pdu() if coap_send() or - * coap_send_large() is not called. + * for the result must be released with coap_delete_pdu() if coap_send() + * is not called. * * @param type The type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON, * COAP_MESSAGE_ACK, COAP_MESSAGE_RST). @@ -366,8 +366,8 @@ coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code, /** * Dispose of an CoAP PDU and frees associated storage. * Not that in general you should not call this function directly. - * When a PDU is sent with coap_send() or coap_send_large(), coap_delete_pdu() - * will be called automatically for you. + * When a PDU is sent with coap_send(), coap_delete_pdu() will be called + * automatically for you. * * @param pdu The PDU for free off. */ diff --git a/libcoap-3.map b/libcoap-3.map index b69b6d9e..ac431930 100644 --- a/libcoap-3.map +++ b/libcoap-3.map @@ -174,7 +174,6 @@ global: coap_send; coap_send_ack; coap_send_error; - coap_send_large; coap_send_message_type; coap_session_disconnected; coap_session_get_ack_random_factor; diff --git a/libcoap-3.sym b/libcoap-3.sym index 6d97fad4..6390d290 100644 --- a/libcoap-3.sym +++ b/libcoap-3.sym @@ -172,7 +172,6 @@ coap_response_phrase coap_send coap_send_ack coap_send_error -coap_send_large coap_send_message_type coap_session_disconnected coap_session_get_ack_random_factor diff --git a/man/coap_block.txt.in b/man/coap_block.txt.in index 810931c3..fbe0be2d 100644 --- a/man/coap_block.txt.in +++ b/man/coap_block.txt.in @@ -15,8 +15,7 @@ coap_context_set_block_mode, coap_add_data_large_request, coap_add_data_large_response, coap_get_data_large, -coap_block_build_body, -coap_send_large +coap_block_build_body - Work with CoAP Blocks SYNOPSIS @@ -43,8 +42,6 @@ const uint8_t **_data_, size_t *_offset_, size_t *_total_);* coap_block_build_body(coap_binary_t *_body_data_, size_t _length_, const uint8_t *_data_, size_t _offset_, size_t _total_);* -*coap_mid_t coap_send_large(coap_session_t *_session_, coap_pdu_t *_pdu_);* - For specific (D)TLS library support, link with *-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, *-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* @@ -172,29 +169,18 @@ is NULL, or _total_ is larger than the current size of _body_data_, then _body_data_ is re-allocated and returned. If there is an error, _body_data_ gets de-allocated. -The *coap_send_large*() function is used to initiate the transmission of a -request type _pdu_ associated with the _session_ in the same way as -*coap_send*() but also sets up a mechanism for handling a (potentially) large -response of data that spans multiple blocks. To get the start of the data -offset and total size, *coap_get_data_large*() needs to be called in the -response handler. If the request includes the OBSERVE option with the observe -value set to 0, then any response that are observe triggered are also handled. - If _block_mode_ (as set by *coap_context_set_block_mode*()) includes -COAP_BLOCK_SINGLE_BODY and *coap_send_large*() is used, then the response -handler will only get called once with the entire body containing the data -from all of the individual blocks. If there is a change of data during the -blocks receipt (e.g. ETag value changes), then the entire set of data is -re-requested and the partial body dropped. +COAP_BLOCK_SINGLE_BODY is used, then the response handler will only get called +once with the entire body containing the data from all of the individual +blocks. If there is a change of data during the blocks receipt (e.g. ETag +value changes), then the entire set of data is re-requested and the partial +body dropped. RETURN VALUES ------------- The *coap_add_data_large_request*(), *coap_add_data_large_response*(), and *coap_get_data_large*() functions return 0 on failure, 1 on success. -The *coap_send_large*() function returns the CoAP message ID on success or -COAP_INVALID_MID on failure. - The *coap_block_build_body*() returns the current state of the body's data (which may have some missing gaps) or NULL on error. @@ -284,7 +270,7 @@ unsigned char *data, size_t length, int observe) { goto error; } - if (coap_send_large(session, pdu) == COAP_INVALID_MID) + if (coap_send(session, pdu) == COAP_INVALID_MID) goto error; return 1; diff --git a/man/coap_observe.txt.in b/man/coap_observe.txt.in index b8a3830e..35fae129 100644 --- a/man/coap_observe.txt.in +++ b/man/coap_observe.txt.in @@ -51,9 +51,10 @@ Optionally, the client can specify query options for the resource, or by using a FETCH request instead of a GET to define a query (RFC8132). To remove the "observe" subscription, the client has to issue a GET (or FETCH) -request with the COAP_OPTION_OBSERVE Option with a value of COAP_OBSERVE_CANCEL. -If the request to "observe" had been sent using *coap_send_large*(), the -"observe" can be cancelled using *coap_cancel_observe*() instead. +request with the COAP_OPTION_OBSERVE Option with a value of +COAP_OBSERVE_CANCEL using the same token and other options used for making the +initial "observe" request. Alternatively, "observe" can be cancelled using +*coap_cancel_observe*() instead. The underlying library adds in and removes "subscribers" to "observe" the resource as appropriate in the server side logic. @@ -111,8 +112,7 @@ server application determines that there has been a change to the state of _resource_. The _query_ parameter is obsolete and ignored. The *coap_cancel_observe*() function can be used by the client to cancel an -observe request that is being tracked following the use of *coap_send_large*() -(See *coap_block*(3)) to send the initial "observe" PDU. This will cause the +observe request that is being tracked. This will cause the appropriate PDU to be sent to the server to cancel the observation, based on the _session_ and _token_ used to set up the observe and the PDU is of type _message_type_ (use COAP_MESSAGE_NON or COAP_MESSAGE_CON). diff --git a/src/block.c b/src/block.c index d9c5cf58..ce6ebdf9 100644 --- a/src/block.c +++ b/src/block.c @@ -282,6 +282,13 @@ coap_cancel_observe(coap_session_t *session, coap_binary_t *token, if (!session) return 0; + if (!(session->block_mode & COAP_BLOCK_USE_LIBCOAP)) { + coap_log(LOG_DEBUG, + "** %s: coap_cancel_observe: COAP_BLOCK_USE_LIBCOAP not enabled\n", + coap_session_str(session)); + return 0; + } + LL_FOREACH(session->lg_crcv, cq) { if (cq->observe_set) { if ((!token && !cq->app_token->length) || (token && @@ -310,7 +317,7 @@ coap_cancel_observe(coap_session_t *session, coap_binary_t *token, coap_encode_var_safe(buf, sizeof(buf), COAP_OBSERVE_CANCEL), buf); - mid = coap_send(session, pdu); + mid = coap_send_internal(session, pdu); if (mid != COAP_INVALID_MID) return 1; break; @@ -345,7 +352,7 @@ coap_add_data_large_internal(coap_session_t *session, if (!(session->block_mode & COAP_BLOCK_USE_LIBCOAP)) { coap_log(LOG_DEBUG, - "** %s: coap_send_large: COAP_BLOCK_USE_LIBCOAP not enabled\n", + "** %s: coap_add_data_large: COAP_BLOCK_USE_LIBCOAP not enabled\n", coap_session_str(session)); goto add_data; } @@ -484,7 +491,7 @@ coap_add_data_large_internal(coap_session_t *session, sizeof(token), token); /* * Token will be updated in pdu later as original pdu may be needed in - * coap_send_large() + * coap_send() */ coap_update_option(pdu, COAP_OPTION_SIZE1, @@ -1123,7 +1130,7 @@ coap_handle_request_send_block(coap_session_t *session, goto internal_issue; } if (i + 1 < request_cnt) { - coap_send(session, out_pdu); + coap_send_internal(session, out_pdu); } } goto skip_app_handler; @@ -1519,7 +1526,7 @@ coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *rcvd) { block.num, block.szx)) goto fail_body; - if (coap_send(session, pdu) == COAP_INVALID_MID) + if (coap_send_internal(session, pdu) == COAP_INVALID_MID) goto fail_body; return 1; } @@ -1592,7 +1599,7 @@ coap_block_build_body(coap_binary_t *body_data, size_t length, * need to initiate the request for the next block and not trouble the * application. Note that Token must unique per request/response. * - * This is set up using coap_send_large() + * This is set up using coap_send() * Client receives large data from server (BLOCK2) * * Return: 0 Call application handler @@ -1711,7 +1718,7 @@ coap_handle_response_get_block(coap_context_t *context, (0 << 4) | (0 << 3) | block.szx), buf); - if (coap_send(session, pdu) == COAP_INVALID_MID) + if (coap_send_internal(session, pdu) == COAP_INVALID_MID) goto fail_resp; goto skip_app_handler; @@ -1788,7 +1795,7 @@ coap_handle_response_get_block(coap_context_t *context, (block.m << 3) | block.szx), buf); - if (coap_send(session, pdu) == COAP_INVALID_MID) + if (coap_send_internal(session, pdu) == COAP_INVALID_MID) goto fail_resp; } if (session->block_mode & (COAP_BLOCK_SINGLE_BODY)) @@ -1894,9 +1901,8 @@ fail_resp: if (recursive == COAP_RECURSE_OK && !p) { if (!sent) { if (coap_get_block(rcvd, COAP_OPTION_BLOCK2, &block)) { - coap_log(LOG_DEBUG, "** %s: large body receive not supported by " - "libcoap unless coap_send_large() is used to transmit " - "request\n", coap_session_str(session)); + coap_log(LOG_DEBUG, "** %s: large body receive internal issue\n", + coap_session_str(session)); } } else if (COAP_RESPONSE_CLASS(rcvd->code) == 2) { diff --git a/src/coap_session.c b/src/coap_session.c index 702e4d5c..7b588019 100644 --- a/src/coap_session.c +++ b/src/coap_session.c @@ -391,7 +391,7 @@ coap_mid_t coap_session_send_ping(coap_session_t *session) { #endif /* !COAP_DISABLE_TCP */ if (!ping) return COAP_INVALID_MID; - return coap_send(session, ping); + return coap_send_internal(session, ping); } void coap_session_connected(coap_session_t *session) { diff --git a/src/net.c b/src/net.c index 50e720cf..d8989dc0 100644 --- a/src/net.c +++ b/src/net.c @@ -755,7 +755,7 @@ coap_send_ack(coap_session_t *session, const coap_pdu_t *request) { COAP_PROTO_NOT_RELIABLE(session->proto)) { response = coap_pdu_init(COAP_MESSAGE_ACK, 0, request->mid, 0); if (response) - result = coap_send(session, response); + result = coap_send_internal(session, response); } return result; } @@ -909,7 +909,7 @@ coap_send_error(coap_session_t *session, response = coap_new_error_response(request, code, opts); if (response) - result = coap_send(session, response); + result = coap_send_internal(session, response); return result; } @@ -923,7 +923,7 @@ coap_send_message_type(coap_session_t *session, const coap_pdu_t *request, if (request) { response = coap_pdu_init(type, 0, request->mid, 0); if (response) - result = coap_send(session, response); + result = coap_send_internal(session, response); } return result; } @@ -1052,7 +1052,7 @@ token_match(const uint8_t *a, size_t alen, } coap_mid_t -coap_send_large(coap_session_t *session, coap_pdu_t *pdu) { +coap_send(coap_session_t *session, coap_pdu_t *pdu) { coap_mid_t mid = COAP_INVALID_MID; coap_lg_crcv_t *lg_crcv = NULL; coap_opt_iterator_t opt_iter; @@ -1063,10 +1063,7 @@ coap_send_large(coap_session_t *session, coap_pdu_t *pdu) { assert(pdu); if (!(session->block_mode & COAP_BLOCK_USE_LIBCOAP)) { - coap_log(LOG_DEBUG, - "** %s: coap_send_large: COAP_BLOCK_USE_LIBCOAP not enabled\n", - coap_session_str(session)); - return coap_send(session, pdu); + return coap_send_internal(session, pdu); } if (COAP_PDU_IS_REQUEST(pdu)) { @@ -1139,7 +1136,7 @@ coap_send_large(coap_session_t *session, coap_pdu_t *pdu) { } send_it: - mid = coap_send(session, pdu); + mid = coap_send_internal(session, pdu); if (lg_crcv) { if (mid != COAP_INVALID_MID) { LL_PREPEND(session->lg_crcv, lg_crcv); @@ -1152,7 +1149,7 @@ send_it: } coap_mid_t -coap_send(coap_session_t *session, coap_pdu_t *pdu) { +coap_send_internal(coap_session_t *session, coap_pdu_t *pdu) { uint8_t r; ssize_t bytes_written; coap_opt_iterator_t opt_iter; @@ -2075,7 +2072,8 @@ coap_new_error_response(const coap_pdu_t *request, coap_pdu_code_t code, } else { /* - * Need space for IP for 5.08 response which is filled in in coap_send() + * Need space for IP for 5.08 response which is filled in in + * coap_send_internal() * https://www.rfc-editor.org/rfc/rfc8768.html#section-4 */ phrase = NULL; @@ -2611,7 +2609,7 @@ handle_request(coap_context_t *context, coap_session_t *session, coap_pdu_t *pdu hop_limit = coap_decode_var_bytes (coap_opt_value (opt), coap_opt_length (opt)); if (hop_limit == 1) { - /* coap_send() will fill in the IP address for us */ + /* coap_send_internal() will fill in the IP address for us */ resp = 508; goto fail_response; } @@ -2716,7 +2714,7 @@ handle_request(coap_context_t *context, coap_session_t *session, coap_pdu_t *pdu if (!resource) { if (response && (no_response(pdu, response, session) != RESPONSE_DROP)) { coap_mid_t mid = pdu->mid; - if (coap_send(session, response) == COAP_INVALID_MID) + if (coap_send_internal(session, response) == COAP_INVALID_MID) coap_log(LOG_WARNING, "cannot send response for mid=0x%x\n", mid); } else { coap_delete_pdu(response); @@ -2845,7 +2843,7 @@ skip_handler: response->used_size = 0; } - if (coap_send(session, response) == COAP_INVALID_MID) { + if (coap_send_internal(session, response) == COAP_INVALID_MID) { coap_log(LOG_DEBUG, "cannot send response for mid=0x%x\n", mid); } } else { @@ -2871,7 +2869,7 @@ skip_handler: if (response && (no_response(pdu, response, session) != RESPONSE_DROP)) { coap_mid_t mid = pdu->mid; - if (coap_send(session, response) == COAP_INVALID_MID) + if (coap_send_internal(session, response) == COAP_INVALID_MID) coap_log(LOG_DEBUG, "cannot send response for mid=0x%x\n", mid); } else { coap_delete_pdu(response); @@ -2889,7 +2887,7 @@ fail_response: &opt_filter); if (response) { coap_mid_t mid = pdu->mid; - if (coap_send(session, response) == COAP_INVALID_MID) + if (coap_send_internal(session, response) == COAP_INVALID_MID) coap_log(LOG_WARNING, "cannot send response for mid=0x%x\n", mid); } } @@ -2962,7 +2960,7 @@ handle_signaling(coap_context_t *context, coap_session_t *session, } if (pong) { coap_add_option(pong, COAP_SIGNALING_OPTION_CUSTODY, 0, NULL); - coap_send(session, pong); + coap_send_internal(session, pong); } } else if (pdu->code == COAP_SIGNALING_CODE_PONG) { session->last_pong = session->last_rx_tx; @@ -3104,7 +3102,7 @@ coap_dispatch(coap_context_t *context, coap_session_t *session, coap_log(LOG_WARNING, "coap_dispatch: cannot create error response\n"); } else { - if (coap_send(session, response) == COAP_INVALID_MID) + if (coap_send_internal(session, response) == COAP_INVALID_MID) coap_log(LOG_WARNING, "coap_dispatch: error sending response\n"); } } diff --git a/src/resource.c b/src/resource.c index 48d496a4..d94fbd59 100644 --- a/src/resource.c +++ b/src/resource.c @@ -966,7 +966,7 @@ coap_notify_observers(coap_context_t *context, coap_resource_t *r, obs->non_cnt++; } - mid = coap_send( obs->session, response ); + mid = coap_send_internal( obs->session, response ); if (COAP_INVALID_MID == mid) { coap_log(LOG_DEBUG,