-
Notifications
You must be signed in to change notification settings - Fork 424
Updating application code from 4.2.1 to 4.3.0
When compiling 4.2.1 based code with a 4.3.0 environment, this will initially throw up many errors as the API has been updated to make future coding simpler, adds more functionality and adds more rigorous coding checks. Updating your code with the following steps will significantly reduce the reported issues.
The examples are now also named with the (D)TLS library type as a suffix. E.g. coap-client is now coap-client-openssl.
Because of the API changes, the libcoap’s include file directory has changed from coap2/ to coap3/. Also, there is now no need to define additional include paths to the compiler options such as -I include/coap3.
Infrequently used parameters (which can easily be recreated) have been removed
and others have been made const. These call-back handlers are those
registered with the coap_register_*() functions as follows:
The definition of coap_method_handler_t has been updated, so all the
functions registered by coap_register_handler() need to be updated. Any
application functions called by these functions may need to include const in
their calling parameters.
Example
4.2.1
static void
hnd_get_time(coap_context_t *context,
coap_resource_t *resource,
coap_session_t *session,
coap_pdu_t *request,
coap_binary_t *token,
coap_string_t *query,
coap_pdu_t *response) {
4.3.0
static void
hnd_get_time(coap_resource_t *resource,
coap_session_t *session,
const coap_pdu_t *request,
const coap_string_t *query,
coap_pdu_t *response) {
If context or token need to be recreated, this is done by
coap_context_t *context = coap_session_get_context(session); coap_bin_const_t rcvd_token = coap_pdu_get_token(request);
The definition of coap_response_handler_t has been updated, so all the
functions registered by coap_register_response_handler() need to be updated.
Any application functions called by these functions may need to include const
in their calling parameters. There is a new handler function exit code
COAP_RESPONSE_FAIL (if the response is not liked and needs to be rejected
with a RST packet) or COAP_RESPONSE_OK. Note that coap_tid_t has been
replaced with coap_mid_t to reflect the parameter is the message id.
Example
4.2.1
static void
message_handler(struct coap_context_t *context,
coap_session_t *session,
coap_pdu_t *sent,
coap_pdu_t *received,
const coap_tid_t id) {
4.3.0
static coap_response_t
message_handler(coap_session_t *session,
const coap_pdu_t *sent,
const coap_pdu_t *received,
const coap_mid_t mid) {
If context needs to be recreated, this is done by
coap_context_t *context = coap_session_get_context(session);
The definition of coap_nack_handler_t has been updated, so all the functions
registered by coap_register_nack_handler() need to be updated. Any
application functions called by these functions may need to include const in
their calling parameters. Note that coap_tid_t has been replaced with
coap_mid_t to reflect the parameter is the message id.
Example
4.2.1
static void
nack_handler(coap_context_t *context,
coap_session_t *session,
coap_pdu_t *sent,
coap_nack_reason_t reason,
const coap_tid_t id) {
4.3.0
static void
nack_handler(coap_session_t *session,
const coap_pdu_t *sent,
const coap_nack_reason_t reason,
const coap_mid_t mid) {
If context needs to be recreated, this is done by
coap_context_t *context = coap_session_get_context(session);
The definition of coap_event_handler_t been updated, so all the functions
registered by coap_register_event_handler() need to be updated. Any
application functions called by these functions may need to include const in
their calling parameters.
Example
4.2.1
static int
event_handler(coap_context_t *context,
coap_event_t event,
struct coap_session_t *session) {
4.3.0
static int
event_handler(coap_session_t *session,
const coap_event_t event) {
Note the reversed order of the parameters. If context needs to be
recreated, this is done by
coap_context_t *context = coap_session_get_context(session);
The definition of coap_ping_handler_t been updated, so all the functions
registered by coap_register_ping_handler() need to be updated. Any
application functions called by these functions may need to include const in
their calling parameters. Note that coap_tid_t has been replaced with
coap_mid_t to reflect the parameter is the message id.
Example
4.2.1
void
ping_handler(coap_context_t *context,
coap_session_t *session,
coap_pdu_t *received,
const coap_tid_t id);
4.3.0
void
ping_handler(coap_session_t *session,
const coap_pdu_t *received,
const coap_mid_t mid);
If context needs to be recreated, this is done by
coap_context_t *context = coap_session_get_context(session);
The definition of coap_pong_handler_t been updated, so all the functions
registered by coap_register_pong_handler() need to be updated. Any
application functions called by these functions may need to include const in
their calling parameters. Note that coap_tid_t has been replaced with
coap_mid_t to reflect the parameter is the message id.
Example
4.2.1
void
pong_handler(coap_context_t *context,
coap_session_t *session,
coap_pdu_t *received,
const coap_tid_t id);
4.3.0
void
pong_handler(coap_session_t *session,
const coap_pdu_t *received,
const coap_mid_t mid);
If context needs to be recreated, this is done by
coap_context_t *context = coap_session_get_context(session);
Many of the structures internally used by libcoap are no longer exposed to
applications. Additional functions of the form coap_X_get_Y() and
coap_X_set_Y() where X is the structure type and Y is the variable. Below
is a non exhaustive set of examples,
Example
4.2.1 if (received->code == 4.3.0 coap_pdu_code_t rcvd_code = coap_pdu_get_code(received); ... if (rcvd_code ==
Example
4.2.1 response->code = COAP_RESPONSE_CODE(404); 4.3.0 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
Note that more descriptive names are now supported for the response codes, but the old form can still be used.
Example
4.2.1 if (received->type == 4.3.0 coap_pdu_code_t rcvd_type = coap_pdu_get_type(received); ... if (rcvd_type ==
Example
4.2.1 request->type = COAP_MESSAGE_NON; 4.3.0 coap_pdu_set_type(request, COAP_MESSAGE_NON);
Example
4.2.1
static inline int
check_token(coap_pdu_t *received) {
return received->token_length == the_token.length &&
memcmp(received->token, the_token.s, the_token.length) == 0;
}
4.3.0
static inline int
check_token(const coap_pdu_t *received) {
coap_bin_const_t rcvd_token = coap_pdu_get_token(received);
return rcvd_token.length == the_token.length &&
memcmp(rcvd_token.s, the_token.s, the_token.length) == 0;
}
Example
4.2.1 if (session->context == 4.3.0 coap_context_t context = coap_session_get_context(session); ... if (context ==
Some functions have had the parameters updated. Below are some of the more common ones.
The definition of the second parameter has changed from coap_request_t to
coap_pdu_code_t.
Example
4.2.1
pdu = coap_pdu_init(msgtype,
COAP_REQUEST_GET,
coap_new_message_id(session),
coap_session_max_pdu_size(session));
4.3.0
pdu = coap_pdu_init(msgtype,
COAP_REQUEST_CODE_GET,
coap_new_message_id(session),
coap_session_max_pdu_size(session));
Note that the second parameter (COAP_REQUEST_CODE_GET) goes further than
just request codes and includes the possibility of response codes (e.g.
COAP_RESPONSE_CODE_CREATED) from the enum coap_pdu_code_t. Hence the
addition of _CODE in the parameter value.
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_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.
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 using this method,
coap_context_set_block_mode() must not be called and none of the _large
functions used.
By calling coap_context_set_block_mode(context, COAP_BLOCK_USE_LIBCOAP) and
using the _large functions, all the existing code that builds the next block
response is no longer needed (and must be removed to prevent packet
request/response duplication) as libcoap does this for the application.
By calling coap_get_data_large(), the application can determine if this is
the first block or not (using offset value), whether the first block is all
the data (offset = 0, length = total) and whether this is the last
block (offset + length = total). It is the responsibility of the
application to re-assemble the individual blocks into a single body of data.
If this is the request handler in a server, the server still needs to return a
2.31 (Continue) response code if the received data is not for the final block,
otherwise a 2.01 (Created) or 2.04 (Changed) should be returned.
By calling coap_context_set_block_mode(context,
COAP_BLOCK_USE_LIBCOAP|COAP_BLOCK_SINGLE_BODY) and using the _large
functions, all the existing code that builds the next block response is no
longer needed (and must be removed to prevent request/response packet
duplication) as libcoap does this for the application.
coap_get_data_large() will only return the entire body of data (offset
always 0, length = total) and there is no need to re-assemble individual
blocks into a large body of data.
In RAM constrained environments, option 2 may be the preferred method.
In the server’s request handler’s call-back, there is no longer any need to check whether this is an Observe call (or Observe triggered requesting additional response call) and add in the Observe Option into the response pdu. This is now added by libcoap, and trying to add in the Observe Option for the 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 prior to sending the initial
request containing the Observe option.
UNUSED_PARAM has been replaced with COAP_UNUSED. If COAP_UNUSED is used,
then the definition for UNUSED_PARAM can be removed.
coap_tid_t has been replaced with coap_mid_t, as well as COAP_TID_INVALID
has been replaced with COAP_MID_INVALID. This is so that the Message ID aligns
with the definition in RFC7252.
The async support has been re-written to simplify usage, and allows the
underlying libcoap to do the main management / work. A primary change is to
register the async request with a defined delay time before triggering - which
if set to 0 is an infinite time and the delay time subsequently updated if
required. Consequently the coap_async_*() functions now have different
parameters.