1= Upgrade from 4.2.1 to 4.3.0 2 3== Summary 4 5When compiling 4.2.1 based code with a 4.3.0 environment, this will initially 6throw up many errors as the API has been updated to make future coding simpler, 7adds more functionality and adds more rigorous coding checks. Updating your 8code with the following steps will significantly reduce the reported issues. 9 10The examples are now also named with the (D)TLS library type as a suffix. 11E.g. coap-client is now coap-client-openssl. 12 13== Include directory changes 14 15Because 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`. 16 17=== Update coap2 to coap3 18 19Example 20---- 214.2.1 22 #include <coap2/coap.h> 234.3.0 24 #include <coap3/coap.h> 25---- 26No other libcoap include files need to be included in your application. 27 28== Call-back handler updates 29 30Infrequently used parameters (which can easily be recreated) have been removed 31and others have been made const. These call-back handlers are those 32registered with the `coap_register_*()` functions as follows: 33 34=== coap_register_handler() 35 36The definition of `coap_method_handler_t` has been updated, so all the 37functions registered by `coap_register_handler()` need to be updated. Any 38application functions called by these functions may need to include `const` in 39their calling parameters. 40 41Example 42---- 434.2.1 44static void 45 hnd_get_time(coap_context_t *context, 46 coap_resource_t *resource, 47 coap_session_t *session, 48 coap_pdu_t *request, 49 coap_binary_t *token, 50 coap_string_t *query, 51 coap_pdu_t *response) { 524.3.0 53 static void 54 hnd_get_time(coap_resource_t *resource, 55 coap_session_t *session, 56 const coap_pdu_t *request, 57 const coap_string_t *query, 58 coap_pdu_t *response) { 59---- 60If `context` or `token` need to be recreated, this is done by 61---- 62 coap_context_t *context = coap_session_get_context(session); 63 coap_bin_const_t rcvd_token = coap_pdu_get_token(request); 64---- 65 66=== coap_register_response_handler() 67 68The definition of `coap_response_handler_t` has been updated, so all the 69functions registered by `coap_register_response_handler()` need to be updated. 70Any application functions called by these functions may need to include `const` 71in their calling parameters. There is a new handler function exit code 72`COAP_RESPONSE_FAIL` (if the response is not liked and needs to be rejected 73with a `RST` packet) or `COAP_RESPONSE_OK`. Note that `coap_tid_t` has been 74replaced with `coap_mid_t` to reflect the parameter is the message id. 75 76Example 77---- 784.2.1 79 static void 80 message_handler(struct coap_context_t *context, 81 coap_session_t *session, 82 coap_pdu_t *sent, 83 coap_pdu_t *received, 84 const coap_tid_t id) { 854.3.0 86 static coap_response_t 87 message_handler(coap_session_t *session, 88 const coap_pdu_t *sent, 89 const coap_pdu_t *received, 90 const coap_mid_t mid) { 91---- 92If `context` needs to be recreated, this is done by 93---- 94 coap_context_t *context = coap_session_get_context(session); 95---- 96 97=== coap_register_nack_handler() 98 99The definition of `coap_nack_handler_t` has been updated, so all the functions 100registered by `coap_register_nack_handler()` need to be updated. Any 101application functions called by these functions may need to include `const` in 102their calling parameters. Note that `coap_tid_t` has been replaced with 103`coap_mid_t` to reflect the parameter is the message id. 104 105Example 106---- 1074.2.1 108 static void 109 nack_handler(coap_context_t *context, 110 coap_session_t *session, 111 coap_pdu_t *sent, 112 coap_nack_reason_t reason, 113 const coap_tid_t id) { 1144.3.0 115 static void 116 nack_handler(coap_session_t *session, 117 const coap_pdu_t *sent, 118 const coap_nack_reason_t reason, 119 const coap_mid_t mid) { 120---- 121If `context` needs to be recreated, this is done by 122---- 123 coap_context_t *context = coap_session_get_context(session); 124---- 125 126=== coap_register_event_handler() 127 128The definition of `coap_event_handler_t` been updated, so all the functions 129registered by `coap_register_event_handler()` need to be updated. Any 130application functions called by these functions may need to include `const` in 131their calling parameters. 132 133Example 134---- 1354.2.1 136 static int 137 event_handler(coap_context_t *context, 138 coap_event_t event, 139 struct coap_session_t *session) { 1404.3.0 141 static int 142 event_handler(coap_session_t *session, 143 const coap_event_t event) { 144---- 145Note the reversed order of the parameters. If `context` needs to be 146recreated, this is done by 147---- 148 coap_context_t *context = coap_session_get_context(session); 149---- 150 151=== coap_register_ping_handler() 152 153The definition of `coap_ping_handler_t` been updated, so all the functions 154registered by `coap_register_ping_handler()` need to be updated. Any 155application functions called by these functions may need to include `const` in 156their calling parameters. Note that `coap_tid_t` has been replaced with 157`coap_mid_t` to reflect the parameter is the message id. 158 159Example 160 161---- 1624.2.1 163 void 164 ping_handler(coap_context_t *context, 165 coap_session_t *session, 166 coap_pdu_t *received, 167 const coap_tid_t id); 1684.3.0 169 void 170 ping_handler(coap_session_t *session, 171 const coap_pdu_t *received, 172 const coap_mid_t mid); 173---- 174If `context` needs to be recreated, this is done by 175---- 176 coap_context_t *context = coap_session_get_context(session); 177---- 178 179=== coap_register_pong_handler() 180 181The definition of `coap_pong_handler_t` been updated, so all the functions 182registered by `coap_register_pong_handler()` need to be updated. Any 183application functions called by these functions may need to include `const` in 184their calling parameters. Note that `coap_tid_t` has been replaced with 185`coap_mid_t` to reflect the parameter is the message id. 186 187Example 188---- 1894.2.1 190 void 191 pong_handler(coap_context_t *context, 192 coap_session_t *session, 193 coap_pdu_t *received, 194 const coap_tid_t id); 1954.3.0 196 void 197 pong_handler(coap_session_t *session, 198 const coap_pdu_t *received, 199 const coap_mid_t mid); 200---- 201If `context` needs to be recreated, this is done by 202---- 203 coap_context_t *context = coap_session_get_context(session); 204---- 205 206== libcoap structures no longer directly accessible 207 208Many of the structures internally used by libcoap are no longer exposed to 209applications. Additional functions of the form `coap_X_get_Y()` and 210`coap_X_set_Y()` where `X` is the structure type and `Y` is the variable. Below 211is a non exhaustive set of examples, 212 213=== coap_pdu_t code variable 214 215 216Example 217---- 2184.2.1 219 if (received->code == 2204.3.0 221 coap_pdu_code_t rcvd_code = coap_pdu_get_code(received); 222 ... 223 if (rcvd_code == 224---- 225 226Example 227---- 2284.2.1 229 response->code = COAP_RESPONSE_CODE(404); 2304.3.0 231 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND); 232---- 233Note that more descriptive names are now supported for the response codes, but 234the old form can still be used. 235 236=== coap_pdu_t type variable 237 238 239Example 240---- 2414.2.1 242 if (received->type == 2434.3.0 244 coap_pdu_code_t rcvd_type = coap_pdu_get_type(received); 245 ... 246 if (rcvd_type == 247---- 248 249Example 250---- 2514.2.1 252 request->type = COAP_MESSAGE_NON; 2534.3.0 254 coap_pdu_set_type(request, COAP_MESSAGE_NON); 255---- 256 257=== coap_pdu_t token variable 258 259 260Example 261---- 2624.2.1 263 static inline int 264 check_token(coap_pdu_t *received) { 265 return received->token_length == the_token.length && 266 memcmp(received->token, the_token.s, the_token.length) == 0; 267 } 2684.3.0 269 static inline int 270 check_token(const coap_pdu_t *received) { 271 coap_bin_const_t rcvd_token = coap_pdu_get_token(received); 272 273 return rcvd_token.length == the_token.length && 274 memcmp(rcvd_token.s, the_token.s, the_token.length) == 0; 275 } 276---- 277 278=== coap_session_t context variable 279 280 281Example 282---- 2834.2.1 284 if (session->context == 2854.3.0 286 coap_context_t context = coap_session_get_context(session); 287 ... 288 if (context == 289---- 290 291=== coap_session_t proto variable 292 293 294Example 295---- 2964.2.1 297 if (session->proto == 2984.3.0 299 coap_proto_t proto = coap_session_get_proto(session); 300 ... 301 if (proto == 302---- 303 304 305== Functions with changed parameters 306 307Some functions have had the parameters updated. Below are some of the more common ones. 308 309=== coap_pdu_init() 310 311The definition of the second parameter has changed from `coap_request_t` to 312`coap_pdu_code_t`. 313 314Example 315---- 3164.2.1 317 pdu = coap_pdu_init(msgtype, 318 COAP_REQUEST_GET, 319 coap_new_message_id(session), 320 coap_session_max_pdu_size(session)); 3214.3.0 322 pdu = coap_pdu_init(msgtype, 323 COAP_REQUEST_CODE_GET, 324 coap_new_message_id(session), 325 coap_session_max_pdu_size(session)); 326---- 327Note that the second parameter (`COAP_REQUEST_CODE_GET`) goes further than 328just request codes and includes the possibility of response codes (e.g. 329`COAP_RESPONSE_CODE_CREATED`) from the `enum coap_pdu_code_t`. Hence the 330addition of `_CODE` in the parameter value. 331 332=== coap_get_data() 333 334The definition of the third parameter has been changed to be `const` 335 336Example 337---- 3384.2.1 339 uint8_t *data; 340 ... 341 ret = coap_get_data(pdu, &length, &data); 3424.3.0 343 const uint8_t *data; 344 ... 345 ret = coap_get_data(pdu, &length, &data); 346---- 347 348== Large Data Handling 349 350Splitting up large data transmission into blocks (RFC7959) can now all be 351handled by internally by libcoap, removing the need for applications to know 352anything about how to work with blocks, or need to do any block packet loss 353recovery. In simple terms, `coap_context_set_block_mode()` must be called, 354`coap_add_data()` (or `coap_add_data_blocked_response()`) is replaced by 355`coap_add_data_large_response()` or `coap_add_data_large_request()`, and 356`coap_get_data_large()` used instead of `coap_get_data()`. See man page 357`coap_block(3)` for further information. 358 359There are 3 ways of handling the block transfers 360 361=== Application does all the work 362 363This is how things were done in 4.2.1. The application recognizes the next 364block request coming in and then generates the next block response (including 365setting up the PDU if client). To continue using this method, 366`coap_context_set_block_mode()` must not be called and none of the `_large` 367functions used. 368 369=== Application sees individual blocks 370 371By calling `coap_context_set_block_mode(context, COAP_BLOCK_USE_LIBCOAP)` and 372using the `_large` functions, all the existing code that builds the next block 373response is no longer needed (and must be removed to prevent packet 374request/response duplication) as libcoap does this for the application. 375 376By calling `coap_get_data_large()`, the application can determine if this is 377the first block or not (using `offset` value), whether the first block is all 378the data (`offset` = `0`, `length` = `total`) and whether this is the last 379block (`offset` + `length` = `total`). It is the responsibility of the 380application to re-assemble the individual blocks into a single body of data. 381 382If this is the request handler in a server, the server still needs to return a 383`2.31 (Continue)` response code if the received data is not for the final block, 384otherwise a `2.01 (Created)` or `2.04 (Changed)` should be returned. 385 386=== Application only sees all the data 387 388By calling `coap_context_set_block_mode(context, 389COAP_BLOCK_USE_LIBCOAP|COAP_BLOCK_SINGLE_BODY)` and using the `_large` 390functions, all the existing code that builds the next block response is no 391longer needed (and must be removed to prevent request/response packet 392duplication) as libcoap does this for the application. 393 394`coap_get_data_large()` will only return the entire body of data (`offset` 395always `0`, `length` = `total`) and there is no need to re-assemble individual 396blocks into a large body of data. 397 398In RAM constrained environments, option 2 may be the preferred method. 399 400== Observe Handling 401 402In the server's request handler's call-back, there is no longer any need to 403check whether this is an Observe call (or Observe triggered requesting 404additional response call) and add in the Observe Option into the response pdu. 405This is now added by libcoap, and trying to add in the Observe Option for the 406second time in the call-back handler will throw up a Informational warning. 407 408For the client, there is a new function `coap_cancel_observe()` that can be 409called to cancel an observation on the server. To use it, 410`coap_context_set_block_mode()` has to be called prior to sending the initial 411request containing the Observe option. 412 413== Unused function parameters 414 415`UNUSED_PARAM` has been replaced with `COAP_UNUSED`. If `COAP_UNUSED` is used, 416then the definition for `UNUSED_PARAM` can be removed. 417 418== CoAP Message IDs 419 420`coap_tid_t` has been replaced with `coap_mid_t`, as well as `COAP_TID_INVALID` 421has been replaced with `COAP_MID_INVALID`. This is so that the Message ID aligns 422with the definition in RFC7252. 423 424== Async Support 425 426The `async` support has been re-written to simplify usage, and allows the 427underlying libcoap to do the main management / work. A primary change is to 428register the async request with a defined delay time before triggering - which 429if set to 0 is an infinite time and the delay time subsequently updated if 430required. Consequently the `coap_async_*()` functions now have different 431parameters. 432