1 /* 2 * Copyright (c) 2017 Linaro Limited 3 * Copyright (c) 2017-2019 Foundries.io 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 /** @file lwm2m.h 9 * 10 * @defgroup lwm2m_api LwM2M high-level API 11 * @ingroup networking 12 * @{ 13 * @brief LwM2M high-level API 14 * 15 * @details 16 * LwM2M high-level interface is defined in this header. 17 * 18 * @note The implementation assumes UDP module is enabled. 19 * 20 * @note For more information refer to Technical Specification 21 * OMA-TS-LightweightM2M_Core-V1_1_1-20190617-A 22 */ 23 24 #ifndef ZEPHYR_INCLUDE_NET_LWM2M_H_ 25 #define ZEPHYR_INCLUDE_NET_LWM2M_H_ 26 27 #include <time.h> 28 #include <zephyr/kernel.h> 29 #include <zephyr/sys/mutex.h> 30 #include <zephyr/net/coap.h> 31 #include <zephyr/net/lwm2m_path.h> 32 33 /** 34 * @name LwM2M Objects managed by OMA for LwM2M tech specification. 35 * Objects in this range have IDs from 0 to 1023. 36 * @{ 37 */ 38 39 /* clang-format off */ 40 #define LWM2M_OBJECT_SECURITY_ID 0 /**< Security object */ 41 #define LWM2M_OBJECT_SERVER_ID 1 /**< Server object */ 42 #define LWM2M_OBJECT_ACCESS_CONTROL_ID 2 /**< Access Control object */ 43 #define LWM2M_OBJECT_DEVICE_ID 3 /**< Device object */ 44 #define LWM2M_OBJECT_CONNECTIVITY_MONITORING_ID 4 /**< Connectivity Monitoring object */ 45 #define LWM2M_OBJECT_FIRMWARE_ID 5 /**< Firmware object */ 46 #define LWM2M_OBJECT_LOCATION_ID 6 /**< Location object */ 47 #define LWM2M_OBJECT_CONNECTIVITY_STATISTICS_ID 7 /**< Connectivity Statistics object */ 48 #define LWM2M_OBJECT_SOFTWARE_MANAGEMENT_ID 9 /**< Software Management object */ 49 #define LWM2M_OBJECT_PORTFOLIO_ID 16 /**< Portfolio object */ 50 #define LWM2M_OBJECT_BINARYAPPDATACONTAINER_ID 19 /**< Binary App Data Container object */ 51 #define LWM2M_OBJECT_EVENT_LOG_ID 20 /**< Event Log object */ 52 #define LWM2M_OBJECT_GATEWAY_ID 25 /**< Gateway object */ 53 /* clang-format on */ 54 55 /** @} */ 56 57 /** 58 * @name LwM2M Objects produced by 3rd party Standards Development 59 * Organizations. 60 * Refer to the OMA LightweightM2M (LwM2M) Object and Resource Registry: 61 * http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html 62 * @{ 63 */ 64 65 /* clang-format off */ 66 #define IPSO_OBJECT_GENERIC_SENSOR_ID 3300 /**< IPSO Generic Sensor object */ 67 #define IPSO_OBJECT_TEMP_SENSOR_ID 3303 /**< IPSO Temperature Sensor object */ 68 #define IPSO_OBJECT_HUMIDITY_SENSOR_ID 3304 /**< IPSO Humidity Sensor object */ 69 #define IPSO_OBJECT_LIGHT_CONTROL_ID 3311 /**< IPSO Light Control object */ 70 #define IPSO_OBJECT_ACCELEROMETER_ID 3313 /**< IPSO Accelerometer object */ 71 #define IPSO_OBJECT_VOLTAGE_SENSOR_ID 3316 /**< IPSO Voltage Sensor object */ 72 #define IPSO_OBJECT_CURRENT_SENSOR_ID 3317 /**< IPSO Current Sensor object */ 73 #define IPSO_OBJECT_PRESSURE_ID 3323 /**< IPSO Pressure Sensor object */ 74 #define IPSO_OBJECT_BUZZER_ID 3338 /**< IPSO Buzzer object */ 75 #define IPSO_OBJECT_TIMER_ID 3340 /**< IPSO Timer object */ 76 #define IPSO_OBJECT_ONOFF_SWITCH_ID 3342 /**< IPSO On/Off Switch object */ 77 #define IPSO_OBJECT_PUSH_BUTTON_ID 3347 /**< IPSO Push Button object */ 78 #define UCIFI_OBJECT_BATTERY_ID 3411 /**< uCIFI Battery object */ 79 #define IPSO_OBJECT_FILLING_LEVEL_SENSOR_ID 3435 /**< IPSO Filling Level Sensor object */ 80 /* clang-format on */ 81 82 /** @} */ 83 84 /** 85 * @brief Callback function called when a socket error is encountered 86 * 87 * @param error Error code 88 */ 89 typedef void (*lwm2m_socket_fault_cb_t)(int error); 90 91 /** @brief LwM2M object path structure */ 92 struct lwm2m_obj_path { 93 uint16_t obj_id; /**< Object ID */ 94 uint16_t obj_inst_id; /**< Object instance ID */ 95 uint16_t res_id; /**< Resource ID */ 96 uint16_t res_inst_id; /**< Resource instance ID */ 97 uint8_t level; /**< Path level (0-4). Ex. 4 = resource instance. */ 98 }; 99 100 /** 101 * @brief Observe callback events 102 */ 103 enum lwm2m_observe_event { 104 LWM2M_OBSERVE_EVENT_OBSERVER_ADDED, /**< Observer added */ 105 LWM2M_OBSERVE_EVENT_OBSERVER_REMOVED, /**< Observer removed */ 106 LWM2M_OBSERVE_EVENT_NOTIFY_ACK, /**< Notification ACKed */ 107 LWM2M_OBSERVE_EVENT_NOTIFY_TIMEOUT, /**< Notification timed out */ 108 }; 109 110 /** 111 * @brief Observe callback indicating observer adds and deletes, and 112 * notification ACKs and timeouts 113 * 114 * @param[in] event Observer add/delete or notification ack/timeout 115 * @param[in] path LwM2M path 116 * @param[in] user_data Pointer to user_data buffer, as provided in 117 * send_traceable_notification(). Used to determine for which 118 * data the ACKed/timed out notification was. 119 */ 120 typedef void (*lwm2m_observe_cb_t)(enum lwm2m_observe_event event, struct lwm2m_obj_path *path, 121 void *user_data); 122 123 124 struct lwm2m_ctx; 125 enum lwm2m_rd_client_event; 126 /** 127 * @brief Asynchronous RD client event callback 128 * 129 * @param[in] ctx LwM2M context generating the event 130 * @param[in] event LwM2M RD client event code 131 */ 132 typedef void (*lwm2m_ctx_event_cb_t)(struct lwm2m_ctx *ctx, 133 enum lwm2m_rd_client_event event); 134 135 136 /** 137 * @brief LwM2M context structure to maintain information for a single 138 * LwM2M connection. 139 */ 140 struct lwm2m_ctx { 141 /** Destination address storage */ 142 struct sockaddr remote_addr; 143 144 /** @cond INTERNAL_HIDDEN 145 * Private CoAP and networking structures + 1 is for RD Client own message 146 */ 147 struct coap_pending pendings[CONFIG_LWM2M_ENGINE_MAX_PENDING + 1]; 148 struct coap_reply replies[CONFIG_LWM2M_ENGINE_MAX_REPLIES + 1]; 149 sys_slist_t pending_sends; 150 #if defined(CONFIG_LWM2M_QUEUE_MODE_ENABLED) 151 sys_slist_t queued_messages; 152 #endif 153 sys_slist_t observer; 154 /** @endcond */ 155 156 /** A pointer to currently processed request, for internal LwM2M engine 157 * use. The underlying type is ``struct lwm2m_message``, but since it's 158 * declared in a private header and not exposed to the application, 159 * it's stored as a void pointer. 160 */ 161 void *processed_req; 162 163 #if defined(CONFIG_LWM2M_DTLS_SUPPORT) || defined(__DOXYGEN__) 164 /** 165 * @name DTLS related information 166 * Available only when @kconfig{CONFIG_LWM2M_DTLS_SUPPORT} is enabled and 167 * @ref lwm2m_ctx.use_dtls is set to true. 168 * @{ 169 */ 170 /** TLS tag is set by client as a reference used when the 171 * LwM2M engine calls tls_credential_(add|delete) 172 */ 173 int tls_tag; 174 175 /** Destination hostname. 176 * When MBEDTLS SNI is enabled socket must be set with destination 177 * server hostname. 178 */ 179 char *desthostname; 180 /** Destination hostname length */ 181 uint16_t desthostnamelen; 182 /** Flag to indicate if hostname verification is enabled */ 183 bool hostname_verify; 184 185 /** Custom load_credentials function. 186 * Client can set load_credentials function as a way of overriding 187 * the default behavior of load_tls_credential() in lwm2m_engine.c 188 */ 189 int (*load_credentials)(struct lwm2m_ctx *client_ctx); 190 /** @} */ 191 #endif 192 /** Custom socket options. 193 * Client can override default socket options by providing 194 * a callback that is called afer a socket is created and before 195 * connect. 196 */ 197 int (*set_socketoptions)(struct lwm2m_ctx *client_ctx); 198 199 /** Flag to indicate if context should use DTLS. 200 * Enabled via the use of coaps:// protocol prefix in connection 201 * information. 202 * NOTE: requires @kconfig{CONFIG_LWM2M_DTLS_SUPPORT} 203 */ 204 bool use_dtls; 205 206 /** 207 * Flag to indicate that the socket connection is suspended. 208 * With queue mode, this will tell if there is a need to reconnect. 209 */ 210 bool connection_suspended; 211 212 #if defined(CONFIG_LWM2M_QUEUE_MODE_ENABLED) || defined(__DOXYGEN__) 213 /** 214 * Flag to indicate that the client is buffering Notifications and Send messages. 215 * True value buffer Notifications and Send messages. 216 */ 217 bool buffer_client_messages; 218 #endif 219 /** Current index of Security Object used for server credentials */ 220 int sec_obj_inst; 221 222 /** Current index of Server Object used in this context. */ 223 int srv_obj_inst; 224 225 /** Flag to enable BOOTSTRAP interface. See Section "Bootstrap Interface" 226 * of LwM2M Technical Specification for more information. 227 */ 228 bool bootstrap_mode; 229 230 /** Socket File Descriptor */ 231 int sock_fd; 232 233 /** Socket fault callback. LwM2M processing thread will call this 234 * callback in case of socket errors on receive. 235 */ 236 lwm2m_socket_fault_cb_t fault_cb; 237 238 /** Callback for new or cancelled observations, and acknowledged or timed 239 * out notifications. 240 */ 241 lwm2m_observe_cb_t observe_cb; 242 243 /** Callback for client events */ 244 lwm2m_ctx_event_cb_t event_cb; 245 246 /** Validation buffer. Used as a temporary buffer to decode the resource 247 * value before validation. On successful validation, its content is 248 * copied into the actual resource buffer. 249 */ 250 uint8_t validate_buf[CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE]; 251 }; 252 253 /** 254 * LwM2M Time series data structure 255 */ 256 struct lwm2m_time_series_elem { 257 /** Cached data Unix timestamp */ 258 time_t t; 259 union { 260 uint8_t u8; 261 uint16_t u16; 262 uint32_t u32; 263 uint64_t u64; 264 int8_t i8; 265 int16_t i16; 266 int32_t i32; 267 int64_t i64; 268 time_t time; 269 double f; 270 bool b; 271 }; 272 }; 273 274 /** 275 * @brief Asynchronous callback to get a resource buffer and length. 276 * 277 * Prior to accessing the data buffer of a resource, the engine can 278 * use this callback to get the buffer pointer and length instead 279 * of using the resource's data buffer. 280 * 281 * The client or LwM2M objects can register a function of this type via: 282 * lwm2m_engine_register_read_callback() 283 * lwm2m_engine_register_pre_write_callback() 284 * 285 * @param[in] obj_inst_id Object instance ID generating the callback. 286 * @param[in] res_id Resource ID generating the callback. 287 * @param[in] res_inst_id Resource instance ID generating the callback 288 * (typically 0 for non-multi instance resources). 289 * @param[out] data_len Length of the data buffer. 290 * 291 * @return Callback returns a pointer to the data buffer or NULL for failure. 292 */ 293 typedef void *(*lwm2m_engine_get_data_cb_t)(uint16_t obj_inst_id, 294 uint16_t res_id, 295 uint16_t res_inst_id, 296 size_t *data_len); 297 298 /** 299 * @brief Asynchronous callback when data has been set to a resource buffer. 300 * 301 * After changing the data of a resource buffer, the LwM2M engine can 302 * make use of this callback to pass the data back to the client or LwM2M 303 * objects. 304 * 305 * A function of this type can be registered via: 306 * lwm2m_engine_register_validate_callback() 307 * lwm2m_engine_register_post_write_callback() 308 * 309 * @param[in] obj_inst_id Object instance ID generating the callback. 310 * @param[in] res_id Resource ID generating the callback. 311 * @param[in] res_inst_id Resource instance ID generating the callback 312 * (typically 0 for non-multi instance resources). 313 * @param[in] data Pointer to data. 314 * @param[in] data_len Length of the data. 315 * @param[in] last_block Flag used during block transfer to indicate the last 316 * block of data. For non-block transfers this is always 317 * false. 318 * @param[in] total_size Expected total size of data for a block transfer. 319 * For non-block transfers this is 0. 320 * 321 * @return Callback returns a negative error code (errno.h) indicating 322 * reason of failure or 0 for success. 323 */ 324 typedef int (*lwm2m_engine_set_data_cb_t)(uint16_t obj_inst_id, 325 uint16_t res_id, uint16_t res_inst_id, 326 uint8_t *data, uint16_t data_len, 327 bool last_block, size_t total_size); 328 329 /** 330 * @brief Asynchronous event notification callback. 331 * 332 * Various object instance and resource-based events in the LwM2M engine 333 * can trigger a callback of this function type: object instance create, 334 * and object instance delete. 335 * 336 * Register a function of this type via: 337 * lwm2m_engine_register_create_callback() 338 * lwm2m_engine_register_delete_callback() 339 * 340 * @param[in] obj_inst_id Object instance ID generating the callback. 341 * 342 * @return Callback returns a negative error code (errno.h) indicating 343 * reason of failure or 0 for success. 344 */ 345 typedef int (*lwm2m_engine_user_cb_t)(uint16_t obj_inst_id); 346 347 /** 348 * @brief Asynchronous execute notification callback. 349 * 350 * Resource executes trigger a callback of this type. 351 * 352 * Register a function of this type via: 353 * lwm2m_engine_register_exec_callback() 354 * 355 * @param[in] obj_inst_id Object instance ID generating the callback. 356 * @param[in] args Pointer to execute arguments payload. (This can be 357 * NULL if no arguments are provided) 358 * @param[in] args_len Length of argument payload in bytes. 359 * 360 * @return Callback returns a negative error code (errno.h) indicating 361 * reason of failure or 0 for success. 362 */ 363 typedef int (*lwm2m_engine_execute_cb_t)(uint16_t obj_inst_id, 364 uint8_t *args, uint16_t args_len); 365 366 /** 367 * @name Power source types used for the "Available Power Sources" resource of 368 * the LwM2M Device object (3/0/6). 369 * @{ 370 */ 371 #define LWM2M_DEVICE_PWR_SRC_TYPE_DC_POWER 0 /**< DC power */ 372 #define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_INT 1 /**< Internal battery */ 373 #define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_EXT 2 /**< External battery */ 374 #define LWM2M_DEVICE_PWR_SRC_TYPE_FUEL_CELL 3 /**< Fuel cell */ 375 #define LWM2M_DEVICE_PWR_SRC_TYPE_PWR_OVER_ETH 4 /**< Power over Ethernet */ 376 #define LWM2M_DEVICE_PWR_SRC_TYPE_USB 5 /**< USB */ 377 #define LWM2M_DEVICE_PWR_SRC_TYPE_AC_POWER 6 /**< AC (mains) power */ 378 #define LWM2M_DEVICE_PWR_SRC_TYPE_SOLAR 7 /**< Solar */ 379 #define LWM2M_DEVICE_PWR_SRC_TYPE_MAX 8 /**< Max value for Available Power Source type */ 380 /** @} */ 381 382 /** 383 * @name Error codes used for the "Error Code" resource of the LwM2M Device 384 * object. 385 * An LwM2M client can register one of the following error codes via 386 * the lwm2m_device_add_err() function. 387 * @{ 388 */ 389 #define LWM2M_DEVICE_ERROR_NONE 0 /**< No error */ 390 #define LWM2M_DEVICE_ERROR_LOW_POWER 1 /**< Low battery power */ 391 #define LWM2M_DEVICE_ERROR_EXT_POWER_SUPPLY_OFF 2 /**< External power supply off */ 392 #define LWM2M_DEVICE_ERROR_GPS_FAILURE 3 /**< GPS module failure */ 393 #define LWM2M_DEVICE_ERROR_LOW_SIGNAL_STRENGTH 4 /**< Low received signal strength */ 394 #define LWM2M_DEVICE_ERROR_OUT_OF_MEMORY 5 /**< Out of memory */ 395 #define LWM2M_DEVICE_ERROR_SMS_FAILURE 6 /**< SMS failure */ 396 #define LWM2M_DEVICE_ERROR_NETWORK_FAILURE 7 /**< IP Connectivity failure */ 397 #define LWM2M_DEVICE_ERROR_PERIPHERAL_FAILURE 8 /**< Peripheral malfunction */ 398 399 /** @} */ 400 401 /** 402 * @name Battery status codes used for the "Battery Status" resource (3/0/20) 403 * of the LwM2M Device object. As the battery status changes, an LwM2M 404 * client can set one of the following codes via: 405 * lwm2m_engine_set_u8("3/0/20", [battery status]) 406 * @{ 407 */ 408 #define LWM2M_DEVICE_BATTERY_STATUS_NORMAL 0 /**< The battery is operating normally and not on 409 * power 410 */ 411 #define LWM2M_DEVICE_BATTERY_STATUS_CHARGING 1 /**< The battery is currently charging */ 412 #define LWM2M_DEVICE_BATTERY_STATUS_CHARGE_COMP 2 /**< The battery is fully charged and the charger 413 * is still connected 414 */ 415 #define LWM2M_DEVICE_BATTERY_STATUS_DAMAGED 3 /**< The battery has some problem */ 416 #define LWM2M_DEVICE_BATTERY_STATUS_LOW 4 /**< The battery is low on charge */ 417 #define LWM2M_DEVICE_BATTERY_STATUS_NOT_INST 5 /**< The battery is not installed */ 418 #define LWM2M_DEVICE_BATTERY_STATUS_UNKNOWN 6 /**< The battery information is not available */ 419 420 /** @} */ 421 422 /** 423 * @brief Register a new error code with LwM2M Device object. 424 * 425 * @param[in] error_code New error code. 426 * 427 * @return 0 for success or negative in case of error. 428 */ 429 int lwm2m_device_add_err(uint8_t error_code); 430 431 432 /** 433 * @name LWM2M Firmware Update object states 434 * 435 * An LwM2M client or the LwM2M Firmware Update object use the following codes 436 * to represent the LwM2M Firmware Update state (5/0/3). 437 * @{ 438 */ 439 440 /** 441 * Idle. Before downloading or after successful updating. 442 */ 443 #define STATE_IDLE 0 444 /** 445 * Downloading. The data sequence is being downloaded. 446 */ 447 #define STATE_DOWNLOADING 1 448 /** 449 * Downloaded. The whole data sequence has been downloaded. 450 */ 451 #define STATE_DOWNLOADED 2 452 /** 453 * Updating. The device is being updated. 454 */ 455 #define STATE_UPDATING 3 456 457 /** @} */ 458 459 /** 460 * @name LWM2M Firmware Update object result codes 461 * 462 * After processing a firmware update, the client sets the result via one of 463 * the following codes via lwm2m_engine_set_u8("5/0/5", [result code]) 464 * @{ 465 */ 466 467 #define RESULT_DEFAULT 0 /**< Initial value */ 468 #define RESULT_SUCCESS 1 /**< Firmware updated successfully */ 469 #define RESULT_NO_STORAGE 2 /**< Not enough flash memory for the new firmware package */ 470 #define RESULT_OUT_OF_MEM 3 /**< Out of RAM during downloading process */ 471 #define RESULT_CONNECTION_LOST 4 /**< Connection lost during downloading process */ 472 #define RESULT_INTEGRITY_FAILED 5 /**< Integrity check failure for new downloaded package */ 473 #define RESULT_UNSUP_FW 6 /**< Unsupported package type */ 474 #define RESULT_INVALID_URI 7 /**< Invalid URI */ 475 #define RESULT_UPDATE_FAILED 8 /**< Firmware update failed */ 476 #define RESULT_UNSUP_PROTO 9 /**< Unsupported protocol */ 477 478 /** @} */ 479 480 #if defined(CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT) || defined(__DOXYGEN__) 481 /** 482 * @brief Set data callback for firmware block transfer. 483 * 484 * LwM2M clients use this function to register a callback for receiving the 485 * block transfer data when performing a firmware update. 486 * 487 * @param[in] cb A callback function to receive the block transfer data 488 */ 489 void lwm2m_firmware_set_write_cb(lwm2m_engine_set_data_cb_t cb); 490 491 /** 492 * @brief Get the data callback for firmware block transfer writes. 493 * 494 * @return A registered callback function to receive the block transfer data 495 */ 496 lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb(void); 497 498 /** 499 * @brief Set data callback for firmware block transfer. 500 * 501 * LwM2M clients use this function to register a callback for receiving the 502 * block transfer data when performing a firmware update. 503 * 504 * @param[in] obj_inst_id Object instance ID 505 * @param[in] cb A callback function to receive the block transfer data 506 */ 507 void lwm2m_firmware_set_write_cb_inst(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb); 508 509 /** 510 * @brief Get the data callback for firmware block transfer writes. 511 * 512 * @param[in] obj_inst_id Object instance ID 513 * @return A registered callback function to receive the block transfer data 514 */ 515 lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb_inst(uint16_t obj_inst_id); 516 517 /** 518 * @brief Set callback for firmware update cancel. 519 * 520 * LwM2M clients use this function to register a callback to perform actions 521 * on firmware update cancel. 522 * 523 * @param[in] cb A callback function perform actions on firmware update cancel. 524 */ 525 void lwm2m_firmware_set_cancel_cb(lwm2m_engine_user_cb_t cb); 526 527 /** 528 * @brief Get a callback for firmware update cancel. 529 * 530 * @return A registered callback function perform actions on firmware update cancel. 531 */ 532 lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb(void); 533 534 /** 535 * @brief Set data callback for firmware update cancel. 536 * 537 * LwM2M clients use this function to register a callback to perform actions 538 * on firmware update cancel. 539 * 540 * @param[in] obj_inst_id Object instance ID 541 * @param[in] cb A callback function perform actions on firmware update cancel. 542 */ 543 void lwm2m_firmware_set_cancel_cb_inst(uint16_t obj_inst_id, lwm2m_engine_user_cb_t cb); 544 545 /** 546 * @brief Get the callback for firmware update cancel. 547 * 548 * @param[in] obj_inst_id Object instance ID 549 * @return A registered callback function perform actions on firmware update cancel. 550 */ 551 lwm2m_engine_user_cb_t lwm2m_firmware_get_cancel_cb_inst(uint16_t obj_inst_id); 552 553 #if defined(CONFIG_LWM2M_FIRMWARE_UPDATE_PULL_SUPPORT) || defined(__DOXYGEN__) 554 /** 555 * @brief Set data callback to handle firmware update execute events. 556 * 557 * LwM2M clients use this function to register a callback for receiving the 558 * update resource "execute" operation on the LwM2M Firmware Update object. 559 * 560 * @param[in] cb A callback function to receive the execute event. 561 */ 562 void lwm2m_firmware_set_update_cb(lwm2m_engine_execute_cb_t cb); 563 564 /** 565 * @brief Get the event callback for firmware update execute events. 566 * 567 * @return A registered callback function to receive the execute event. 568 */ 569 lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb(void); 570 571 /** 572 * @brief Set data callback to handle firmware update execute events. 573 * 574 * LwM2M clients use this function to register a callback for receiving the 575 * update resource "execute" operation on the LwM2M Firmware Update object. 576 * 577 * @param[in] obj_inst_id Object instance ID 578 * @param[in] cb A callback function to receive the execute event. 579 */ 580 void lwm2m_firmware_set_update_cb_inst(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb); 581 582 /** 583 * @brief Get the event callback for firmware update execute events. 584 * 585 * @param[in] obj_inst_id Object instance ID 586 * @return A registered callback function to receive the execute event. 587 */ 588 lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb_inst(uint16_t obj_inst_id); 589 #endif 590 #endif 591 592 593 #if defined(CONFIG_LWM2M_SWMGMT_OBJ_SUPPORT) || defined(__DOXYGEN__) 594 595 /** 596 * @brief Set callback to handle software activation requests 597 * 598 * The callback will be executed when the LWM2M execute operation gets called 599 * on the corresponding object's Activate resource instance. 600 * 601 * @param[in] obj_inst_id The instance number to set the callback for. 602 * @param[in] cb A callback function to receive the execute event. 603 * 604 * @return 0 on success, otherwise a negative integer. 605 */ 606 int lwm2m_swmgmt_set_activate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb); 607 608 /** 609 * @brief Set callback to handle software deactivation requests 610 * 611 * The callback will be executed when the LWM2M execute operation gets called 612 * on the corresponding object's Deactivate resource instance. 613 * 614 * @param[in] obj_inst_id The instance number to set the callback for. 615 * @param[in] cb A callback function to receive the execute event. 616 * 617 * @return 0 on success, otherwise a negative integer. 618 */ 619 int lwm2m_swmgmt_set_deactivate_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb); 620 621 /** 622 * @brief Set callback to handle software install requests 623 * 624 * The callback will be executed when the LWM2M execute operation gets called 625 * on the corresponding object's Install resource instance. 626 * 627 * @param[in] obj_inst_id The instance number to set the callback for. 628 * @param[in] cb A callback function to receive the execute event. 629 * 630 * @return 0 on success, otherwise a negative integer. 631 */ 632 int lwm2m_swmgmt_set_install_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb); 633 634 /** 635 * @brief Set callback to handle software uninstall requests 636 * 637 * The callback will be executed when the LWM2M execute operation gets called 638 * on the corresponding object's Uninstall resource instance. 639 * 640 * @param[in] obj_inst_id The instance number to set the callback for. 641 * @param[in] cb A callback function for handling the execute event. 642 * 643 * @return 0 on success, otherwise a negative integer. 644 */ 645 int lwm2m_swmgmt_set_delete_package_cb(uint16_t obj_inst_id, lwm2m_engine_execute_cb_t cb); 646 647 /** 648 * @brief Set callback to read software package 649 * 650 * The callback will be executed when the LWM2M read operation gets called 651 * on the corresponding object. 652 * 653 * @param[in] obj_inst_id The instance number to set the callback for. 654 * @param[in] cb A callback function for handling the read event. 655 * 656 * @return 0 on success, otherwise a negative integer. 657 */ 658 int lwm2m_swmgmt_set_read_package_version_cb(uint16_t obj_inst_id, lwm2m_engine_get_data_cb_t cb); 659 660 /** 661 * @brief Set data callback for software management block transfer. 662 * 663 * The callback will be executed when the LWM2M block write operation gets called 664 * on the corresponding object's resource instance. 665 * 666 * @param[in] obj_inst_id The instance number to set the callback for. 667 * @param[in] cb A callback function for handling the block write event. 668 * 669 * @return 0 on success, otherwise a negative integer. 670 */ 671 int lwm2m_swmgmt_set_write_package_cb(uint16_t obj_inst_id, lwm2m_engine_set_data_cb_t cb); 672 673 /** 674 * Function to be called when a Software Management object instance 675 * completed the Install operation. 676 * 677 * @param[in] obj_inst_id The Software Management object instance 678 * @param[in] error_code The result code of the operation. Zero on success 679 * otherwise it should be a negative integer. 680 * 681 * return 0 on success, otherwise a negative integer. 682 */ 683 int lwm2m_swmgmt_install_completed(uint16_t obj_inst_id, int error_code); 684 685 #endif 686 687 #if defined(CONFIG_LWM2M_EVENT_LOG_OBJ_SUPPORT) || defined(__DOXYGEN__) 688 689 /** 690 * @brief Set callback to read log data 691 * 692 * The callback will be executed when the LWM2M read operation gets called 693 * on the corresponding object. 694 * 695 * @param[in] cb A callback function for handling the read event. 696 */ 697 void lwm2m_event_log_set_read_log_data_cb(lwm2m_engine_get_data_cb_t cb); 698 699 #endif 700 701 /** 702 * @brief Maximum value for Objlnk resource fields 703 */ 704 #define LWM2M_OBJLNK_MAX_ID USHRT_MAX 705 706 /** 707 * @brief LWM2M Objlnk resource type structure 708 */ 709 struct lwm2m_objlnk { 710 uint16_t obj_id; /**< Object ID */ 711 uint16_t obj_inst; /**< Object instance ID */ 712 }; 713 714 /** 715 * @brief Change an observer's pmin value. 716 * 717 * @deprecated Use lwm2m_update_observer_min_period() instead. 718 * 719 * LwM2M clients use this function to modify the pmin attribute 720 * for an observation being made. 721 * Example to update the pmin of a temperature sensor value being observed: 722 * lwm2m_engine_update_observer_min_period("client_ctx, 3303/0/5700", 5); 723 * 724 * @param[in] client_ctx LwM2M context 725 * @param[in] pathstr LwM2M path string "obj/obj-inst/res" 726 * @param[in] period_s Value of pmin to be given (in seconds). 727 * 728 * @return 0 for success or negative in case of error. 729 */ 730 __deprecated 731 int lwm2m_engine_update_observer_min_period(struct lwm2m_ctx *client_ctx, const char *pathstr, 732 uint32_t period_s); 733 734 /** 735 * @brief Change an observer's pmin value. 736 * 737 * LwM2M clients use this function to modify the pmin attribute 738 * for an observation being made. 739 * Example to update the pmin of a temperature sensor value being observed: 740 * lwm2m_update_observer_min_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5); 741 * 742 * @param[in] client_ctx LwM2M context 743 * @param[in] path LwM2M path as a struct 744 * @param[in] period_s Value of pmin to be given (in seconds). 745 * 746 * @return 0 for success or negative in case of error. 747 */ 748 int lwm2m_update_observer_min_period(struct lwm2m_ctx *client_ctx, 749 const struct lwm2m_obj_path *path, uint32_t period_s); 750 751 /** 752 * @brief Change an observer's pmax value. 753 * 754 * @deprecated Use lwm2m_update_observer_max_period() instead. 755 * 756 * LwM2M clients use this function to modify the pmax attribute 757 * for an observation being made. 758 * Example to update the pmax of a temperature sensor value being observed: 759 * lwm2m_engine_update_observer_max_period("client_ctx, 3303/0/5700", 5); 760 * 761 * @param[in] client_ctx LwM2M context 762 * @param[in] pathstr LwM2M path string "obj/obj-inst/res" 763 * @param[in] period_s Value of pmax to be given (in seconds). 764 * 765 * @return 0 for success or negative in case of error. 766 */ 767 __deprecated 768 int lwm2m_engine_update_observer_max_period(struct lwm2m_ctx *client_ctx, const char *pathstr, 769 uint32_t period_s); 770 771 /** 772 * @brief Change an observer's pmax value. 773 * 774 * LwM2M clients use this function to modify the pmax attribute 775 * for an observation being made. 776 * Example to update the pmax of a temperature sensor value being observed: 777 * lwm2m__update_observer_max_period(client_ctx, &LWM2M_OBJ(3303, 0, 5700), 5); 778 * 779 * @param[in] client_ctx LwM2M context 780 * @param[in] path LwM2M path as a struct 781 * @param[in] period_s Value of pmax to be given (in seconds). 782 * 783 * @return 0 for success or negative in case of error. 784 */ 785 int lwm2m_update_observer_max_period(struct lwm2m_ctx *client_ctx, 786 const struct lwm2m_obj_path *path, uint32_t period_s); 787 788 /** 789 * @brief Create an LwM2M object instance. 790 * 791 * @deprecated Use lwm2m_create_obj_inst() instead. 792 * 793 * LwM2M clients use this function to create non-default LwM2M objects: 794 * Example to create first temperature sensor object: 795 * lwm2m_engine_create_obj_inst("3303/0"); 796 * 797 * @param[in] pathstr LwM2M path string "obj/obj-inst" 798 * 799 * @return 0 for success or negative in case of error. 800 */ 801 __deprecated 802 int lwm2m_engine_create_obj_inst(const char *pathstr); 803 804 /** 805 * @brief Create an LwM2M object instance. 806 * 807 * LwM2M clients use this function to create non-default LwM2M objects: 808 * Example to create first temperature sensor object: 809 * lwm2m_create_obj_inst(&LWM2M_OBJ(3303, 0)); 810 * 811 * @param[in] path LwM2M path as a struct 812 * 813 * @return 0 for success or negative in case of error. 814 */ 815 int lwm2m_create_object_inst(const struct lwm2m_obj_path *path); 816 817 /** 818 * @brief Delete an LwM2M object instance. 819 * 820 * @deprecated Use lwm2m_delete_obj_inst() instead. 821 * 822 * LwM2M clients use this function to delete LwM2M objects. 823 * 824 * @param[in] pathstr LwM2M path string "obj/obj-inst" 825 * 826 * @return 0 for success or negative in case of error. 827 */ 828 __deprecated 829 int lwm2m_engine_delete_obj_inst(const char *pathstr); 830 831 /** 832 * @brief Delete an LwM2M object instance. 833 * 834 * LwM2M clients use this function to delete LwM2M objects. 835 * 836 * @param[in] path LwM2M path as a struct 837 * 838 * @return 0 for success or negative in case of error. 839 */ 840 int lwm2m_delete_object_inst(const struct lwm2m_obj_path *path); 841 842 /** 843 * @brief Locks the registry for this thread. 844 * 845 * Use this function before writing to multiple resources. This halts the 846 * lwm2m main thread until all the write-operations are finished. 847 * 848 */ 849 void lwm2m_registry_lock(void); 850 851 /** 852 * @brief Unlocks the registry previously locked by lwm2m_registry_lock(). 853 * 854 */ 855 void lwm2m_registry_unlock(void); 856 857 /** 858 * @brief Set resource (instance) value (opaque buffer) 859 * 860 * @deprecated Use lwm2m_set_opaque() instead. 861 * 862 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 863 * @param[in] data_ptr Data buffer 864 * @param[in] data_len Length of buffer 865 * 866 * @return 0 for success or negative in case of error. 867 */ 868 __deprecated 869 int lwm2m_engine_set_opaque(const char *pathstr, const char *data_ptr, uint16_t data_len); 870 871 /** 872 * @brief Set resource (instance) value (opaque buffer) 873 * 874 * @param[in] path LwM2M path as a struct 875 * @param[in] data_ptr Data buffer 876 * @param[in] data_len Length of buffer 877 * 878 * @return 0 for success or negative in case of error. 879 */ 880 int lwm2m_set_opaque(const struct lwm2m_obj_path *path, const char *data_ptr, uint16_t data_len); 881 882 /** 883 * @brief Set resource (instance) value (string) 884 * 885 * @deprecated Use lwm2m_set_string() instead. 886 * 887 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 888 * @param[in] data_ptr NULL terminated char buffer 889 * 890 * @return 0 for success or negative in case of error. 891 */ 892 __deprecated 893 int lwm2m_engine_set_string(const char *pathstr, const char *data_ptr); 894 895 /** 896 * @brief Set resource (instance) value (string) 897 * 898 * @param[in] path LwM2M path as a struct 899 * @param[in] data_ptr NULL terminated char buffer 900 * 901 * @return 0 for success or negative in case of error. 902 */ 903 int lwm2m_set_string(const struct lwm2m_obj_path *path, const char *data_ptr); 904 905 /** 906 * @brief Set resource (instance) value (u8) 907 * 908 * @deprecated Use lwm2m_set_u8() instead. 909 * 910 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 911 * @param[in] value u8 value 912 * 913 * @return 0 for success or negative in case of error. 914 */ 915 __deprecated 916 int lwm2m_engine_set_u8(const char *pathstr, uint8_t value); 917 918 /** 919 * @brief Set resource (instance) value (u8) 920 * 921 * @param[in] path LwM2M path as a struct 922 * @param[in] value u8 value 923 * 924 * @return 0 for success or negative in case of error. 925 */ 926 int lwm2m_set_u8(const struct lwm2m_obj_path *path, uint8_t value); 927 928 /** 929 * @brief Set resource (instance) value (u16) 930 * 931 * @deprecated Use lwm2m_set_u16() instead. 932 * 933 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 934 * @param[in] value u16 value 935 * 936 * @return 0 for success or negative in case of error. 937 */ 938 __deprecated 939 int lwm2m_engine_set_u16(const char *pathstr, uint16_t value); 940 941 /** 942 * @brief Set resource (instance) value (u16) 943 * 944 * @param[in] path LwM2M path as a struct 945 * @param[in] value u16 value 946 * 947 * @return 0 for success or negative in case of error. 948 */ 949 int lwm2m_set_u16(const struct lwm2m_obj_path *path, uint16_t value); 950 951 /** 952 * @brief Set resource (instance) value (u32) 953 * 954 * @deprecated Use lwm2m_set_u32() instead. 955 * 956 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 957 * @param[in] value u32 value 958 * 959 * @return 0 for success or negative in case of error. 960 */ 961 __deprecated 962 int lwm2m_engine_set_u32(const char *pathstr, uint32_t value); 963 964 /** 965 * @brief Set resource (instance) value (u32) 966 * 967 * @param[in] path LwM2M path as a struct 968 * @param[in] value u32 value 969 * 970 * @return 0 for success or negative in case of error. 971 */ 972 int lwm2m_set_u32(const struct lwm2m_obj_path *path, uint32_t value); 973 974 /** 975 * @brief Set resource (instance) value (u64) 976 * 977 * @deprecated Use lwm2m_set_u64() instead. 978 * 979 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 980 * @param[in] value u64 value 981 * 982 * @return 0 for success or negative in case of error. 983 */ 984 __deprecated 985 int lwm2m_engine_set_u64(const char *pathstr, uint64_t value); 986 987 /** 988 * @brief Set resource (instance) value (u64) 989 * 990 * @param[in] path LwM2M path as a struct 991 * @param[in] value u64 value 992 * 993 * @return 0 for success or negative in case of error. 994 */ 995 int lwm2m_set_u64(const struct lwm2m_obj_path *path, uint64_t value); 996 997 /** 998 * @brief Set resource (instance) value (s8) 999 * 1000 * @deprecated Use lwm2m_set_s8() instead. 1001 * 1002 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1003 * @param[in] value s8 value 1004 * 1005 * @return 0 for success or negative in case of error. 1006 */ 1007 __deprecated 1008 int lwm2m_engine_set_s8(const char *pathstr, int8_t value); 1009 1010 /** 1011 * @brief Set resource (instance) value (s8) 1012 * 1013 * @param[in] path LwM2M path as a struct 1014 * @param[in] value s8 value 1015 * 1016 * @return 0 for success or negative in case of error. 1017 */ 1018 int lwm2m_set_s8(const struct lwm2m_obj_path *path, int8_t value); 1019 1020 /** 1021 * @brief Set resource (instance) value (s16) 1022 * 1023 * @deprecated Use lwm2m_set_s16() instead. 1024 * 1025 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1026 * @param[in] value s16 value 1027 * 1028 * @return 0 for success or negative in case of error. 1029 */ 1030 __deprecated 1031 int lwm2m_engine_set_s16(const char *pathstr, int16_t value); 1032 1033 /** 1034 * @brief Set resource (instance) value (s16) 1035 * 1036 * @param[in] path LwM2M path as a struct 1037 * @param[in] value s16 value 1038 * 1039 * @return 0 for success or negative in case of error. 1040 */ 1041 int lwm2m_set_s16(const struct lwm2m_obj_path *path, int16_t value); 1042 1043 /** 1044 * @brief Set resource (instance) value (s32) 1045 * 1046 * @deprecated Use lwm2m_set_s32() instead. 1047 * 1048 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1049 * @param[in] value s32 value 1050 * 1051 * @return 0 for success or negative in case of error. 1052 */ 1053 __deprecated 1054 int lwm2m_engine_set_s32(const char *pathstr, int32_t value); 1055 1056 /** 1057 * @brief Set resource (instance) value (s32) 1058 * 1059 * @param[in] path LwM2M path as a struct 1060 * @param[in] value s32 value 1061 * 1062 * @return 0 for success or negative in case of error. 1063 */ 1064 int lwm2m_set_s32(const struct lwm2m_obj_path *path, int32_t value); 1065 1066 /** 1067 * @brief Set resource (instance) value (s64) 1068 * 1069 * @deprecated Use lwm2m_set_s64() instead. 1070 * 1071 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1072 * @param[in] value s64 value 1073 * 1074 * @return 0 for success or negative in case of error. 1075 */ 1076 __deprecated 1077 int lwm2m_engine_set_s64(const char *pathstr, int64_t value); 1078 1079 /** 1080 * @brief Set resource (instance) value (s64) 1081 * 1082 * @param[in] path LwM2M path as a struct 1083 * @param[in] value s64 value 1084 * 1085 * @return 0 for success or negative in case of error. 1086 */ 1087 int lwm2m_set_s64(const struct lwm2m_obj_path *path, int64_t value); 1088 1089 /** 1090 * @brief Set resource (instance) value (bool) 1091 * 1092 * @deprecated Use lwm2m_set_bool() instead. 1093 * 1094 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1095 * @param[in] value bool value 1096 * 1097 * @return 0 for success or negative in case of error. 1098 */ 1099 __deprecated 1100 int lwm2m_engine_set_bool(const char *pathstr, bool value); 1101 1102 /** 1103 * @brief Set resource (instance) value (bool) 1104 * 1105 * @param[in] path LwM2M path as a struct 1106 * @param[in] value bool value 1107 * 1108 * @return 0 for success or negative in case of error. 1109 */ 1110 int lwm2m_set_bool(const struct lwm2m_obj_path *path, bool value); 1111 1112 /** 1113 * @brief Set resource (instance) value (double) 1114 * 1115 * @deprecated Use lwm2m_set_f64() instead. 1116 * 1117 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1118 * @param[in] value double value 1119 * 1120 * @return 0 for success or negative in case of error. 1121 */ 1122 __deprecated 1123 int lwm2m_engine_set_float(const char *pathstr, const double *value); 1124 1125 /** 1126 * @brief Set resource (instance) value (double) 1127 * 1128 * @param[in] path LwM2M path as a struct 1129 * @param[in] value double value 1130 * 1131 * @return 0 for success or negative in case of error. 1132 */ 1133 int lwm2m_set_f64(const struct lwm2m_obj_path *path, const double value); 1134 1135 /** 1136 * @brief Set resource (instance) value (Objlnk) 1137 * 1138 * @deprecated Use lwm2m_set_objlnk() instead. 1139 * 1140 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1141 * @param[in] value pointer to the lwm2m_objlnk structure 1142 * 1143 * @return 0 for success or negative in case of error. 1144 */ 1145 __deprecated 1146 int lwm2m_engine_set_objlnk(const char *pathstr, const struct lwm2m_objlnk *value); 1147 1148 /** 1149 * @brief Set resource (instance) value (Objlnk) 1150 * 1151 * @param[in] path LwM2M path as a struct 1152 * @param[in] value pointer to the lwm2m_objlnk structure 1153 * 1154 * @return 0 for success or negative in case of error. 1155 */ 1156 int lwm2m_set_objlnk(const struct lwm2m_obj_path *path, const struct lwm2m_objlnk *value); 1157 1158 /** 1159 * @brief Set resource (instance) value (Time) 1160 * 1161 * @deprecated Use lwm2m_set_time() instead. 1162 * 1163 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1164 * @param[in] value Epoch timestamp 1165 * 1166 * @return 0 for success or negative in case of error. 1167 */ 1168 __deprecated 1169 int lwm2m_engine_set_time(const char *pathstr, time_t value); 1170 1171 /** 1172 * @brief Set resource (instance) value (Time) 1173 * 1174 * @param[in] path LwM2M path as a struct 1175 * @param[in] value Epoch timestamp 1176 * 1177 * @return 0 for success or negative in case of error. 1178 */ 1179 int lwm2m_set_time(const struct lwm2m_obj_path *path, time_t value); 1180 1181 /** 1182 * @brief Get resource (instance) value (opaque buffer) 1183 * 1184 * @deprecated Use lwm2m_get_opaque() instead. 1185 * 1186 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1187 * @param[out] buf Data buffer to copy data into 1188 * @param[in] buflen Length of buffer 1189 * 1190 * @return 0 for success or negative in case of error. 1191 */ 1192 __deprecated 1193 int lwm2m_engine_get_opaque(const char *pathstr, void *buf, uint16_t buflen); 1194 1195 /** 1196 * @brief Get resource (instance) value (opaque buffer) 1197 * 1198 * @param[in] path LwM2M path as a struct 1199 * @param[out] buf Data buffer to copy data into 1200 * @param[in] buflen Length of buffer 1201 * 1202 * @return 0 for success or negative in case of error. 1203 */ 1204 int lwm2m_get_opaque(const struct lwm2m_obj_path *path, void *buf, uint16_t buflen); 1205 1206 /** 1207 * @brief Get resource (instance) value (string) 1208 * 1209 * @deprecated Use lwm2m_get_string() instead. 1210 * 1211 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1212 * @param[out] str String buffer to copy data into 1213 * @param[in] buflen Length of buffer 1214 * 1215 * @return 0 for success or negative in case of error. 1216 */ 1217 __deprecated 1218 int lwm2m_engine_get_string(const char *pathstr, void *str, uint16_t buflen); 1219 1220 /** 1221 * @brief Get resource (instance) value (string) 1222 * 1223 * @param[in] path LwM2M path as a struct 1224 * @param[out] str String buffer to copy data into 1225 * @param[in] buflen Length of buffer 1226 * 1227 * @return 0 for success or negative in case of error. 1228 */ 1229 int lwm2m_get_string(const struct lwm2m_obj_path *path, void *str, uint16_t buflen); 1230 1231 /** 1232 * @brief Get resource (instance) value (u8) 1233 * 1234 * @deprecated Use lwm2m_get_u8() instead. 1235 * 1236 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1237 * @param[out] value u8 buffer to copy data into 1238 * 1239 * @return 0 for success or negative in case of error. 1240 */ 1241 __deprecated 1242 int lwm2m_engine_get_u8(const char *pathstr, uint8_t *value); 1243 1244 /** 1245 * @brief Get resource (instance) value (u8) 1246 * 1247 * @param[in] path LwM2M path as a struct 1248 * @param[out] value u8 buffer to copy data into 1249 * 1250 * @return 0 for success or negative in case of error. 1251 */ 1252 int lwm2m_get_u8(const struct lwm2m_obj_path *path, uint8_t *value); 1253 1254 /** 1255 * @brief Get resource (instance) value (u16) 1256 * 1257 * @deprecated Use lwm2m_get_u16() instead. 1258 * 1259 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1260 * @param[out] value u16 buffer to copy data into 1261 * 1262 * @return 0 for success or negative in case of error. 1263 */ 1264 __deprecated 1265 int lwm2m_engine_get_u16(const char *pathstr, uint16_t *value); 1266 1267 /** 1268 * @brief Get resource (instance) value (u16) 1269 * 1270 * @param[in] path LwM2M path as a struct 1271 * @param[out] value u16 buffer to copy data into 1272 * 1273 * @return 0 for success or negative in case of error. 1274 */ 1275 int lwm2m_get_u16(const struct lwm2m_obj_path *path, uint16_t *value); 1276 1277 /** 1278 * @brief Get resource (instance) value (u32) 1279 * 1280 * @deprecated Use lwm2m_get_u32() instead. 1281 * 1282 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1283 * @param[out] value u32 buffer to copy data into 1284 * 1285 * @return 0 for success or negative in case of error. 1286 */ 1287 __deprecated 1288 int lwm2m_engine_get_u32(const char *pathstr, uint32_t *value); 1289 1290 /** 1291 * @brief Get resource (instance) value (u32) 1292 * 1293 * @param[in] path LwM2M path as a struct 1294 * @param[out] value u32 buffer to copy data into 1295 * 1296 * @return 0 for success or negative in case of error. 1297 */ 1298 int lwm2m_get_u32(const struct lwm2m_obj_path *path, uint32_t *value); 1299 1300 /** 1301 * @brief Get resource (instance) value (u64) 1302 * 1303 * @deprecated Use lwm2m_get_u64() instead. 1304 * 1305 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1306 * @param[out] value u64 buffer to copy data into 1307 * 1308 * @return 0 for success or negative in case of error. 1309 */ 1310 __deprecated 1311 int lwm2m_engine_get_u64(const char *pathstr, uint64_t *value); 1312 1313 /** 1314 * @brief Get resource (instance) value (u64) 1315 * 1316 * @param[in] path LwM2M path as a struct 1317 * @param[out] value u64 buffer to copy data into 1318 * 1319 * @return 0 for success or negative in case of error. 1320 */ 1321 int lwm2m_get_u64(const struct lwm2m_obj_path *path, uint64_t *value); 1322 1323 /** 1324 * @brief Get resource (instance) value (s8) 1325 * 1326 * @deprecated Use lwm2m_get_s8() instead. 1327 * 1328 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1329 * @param[out] value s8 buffer to copy data into 1330 * 1331 * @return 0 for success or negative in case of error. 1332 */ 1333 __deprecated 1334 int lwm2m_engine_get_s8(const char *pathstr, int8_t *value); 1335 1336 /** 1337 * @brief Get resource (instance) value (s8) 1338 * 1339 * @param[in] path LwM2M path as a struct 1340 * @param[out] value s8 buffer to copy data into 1341 * 1342 * @return 0 for success or negative in case of error. 1343 */ 1344 int lwm2m_get_s8(const struct lwm2m_obj_path *path, int8_t *value); 1345 1346 /** 1347 * @brief Get resource (instance) value (s16) 1348 * 1349 * @deprecated Use lwm2m_get_s16() instead. 1350 * 1351 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1352 * @param[out] value s16 buffer to copy data into 1353 * 1354 * @return 0 for success or negative in case of error. 1355 */ 1356 __deprecated 1357 int lwm2m_engine_get_s16(const char *pathstr, int16_t *value); 1358 1359 /** 1360 * @brief Get resource (instance) value (s16) 1361 * 1362 * @param[in] path LwM2M path as a struct 1363 * @param[out] value s16 buffer to copy data into 1364 * 1365 * @return 0 for success or negative in case of error. 1366 */ 1367 int lwm2m_get_s16(const struct lwm2m_obj_path *path, int16_t *value); 1368 1369 /** 1370 * @brief Get resource (instance) value (s32) 1371 * 1372 * @deprecated Use lwm2m_get_s32() instead. 1373 * 1374 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1375 * @param[out] value s32 buffer to copy data into 1376 * 1377 * @return 0 for success or negative in case of error. 1378 */ 1379 __deprecated 1380 int lwm2m_engine_get_s32(const char *pathstr, int32_t *value); 1381 1382 /** 1383 * @brief Get resource (instance) value (s32) 1384 * 1385 * @param[in] path LwM2M path as a struct 1386 * @param[out] value s32 buffer to copy data into 1387 * 1388 * @return 0 for success or negative in case of error. 1389 */ 1390 int lwm2m_get_s32(const struct lwm2m_obj_path *path, int32_t *value); 1391 1392 /** 1393 * @brief Get resource (instance) value (s64) 1394 * 1395 * @deprecated Use lwm2m_get_s64() instead. 1396 * 1397 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1398 * @param[out] value s64 buffer to copy data into 1399 * 1400 * @return 0 for success or negative in case of error. 1401 */ 1402 __deprecated 1403 int lwm2m_engine_get_s64(const char *pathstr, int64_t *value); 1404 1405 /** 1406 * @brief Get resource (instance) value (s64) 1407 * 1408 * @param[in] path LwM2M path as a struct 1409 * @param[out] value s64 buffer to copy data into 1410 * 1411 * @return 0 for success or negative in case of error. 1412 */ 1413 int lwm2m_get_s64(const struct lwm2m_obj_path *path, int64_t *value); 1414 1415 /** 1416 * @brief Get resource (instance) value (bool) 1417 * 1418 * @deprecated Use lwm2m_get_bool() instead. 1419 * 1420 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1421 * @param[out] value bool buffer to copy data into 1422 * 1423 * @return 0 for success or negative in case of error. 1424 */ 1425 __deprecated 1426 int lwm2m_engine_get_bool(const char *pathstr, bool *value); 1427 1428 /** 1429 * @brief Get resource (instance) value (bool) 1430 * 1431 * @param[in] path LwM2M path as a struct 1432 * @param[out] value bool buffer to copy data into 1433 * 1434 * @return 0 for success or negative in case of error. 1435 */ 1436 int lwm2m_get_bool(const struct lwm2m_obj_path *path, bool *value); 1437 1438 /** 1439 * @brief Get resource (instance) value (double) 1440 * 1441 * @deprecated Use lwm2m_get_f64() instead. 1442 * 1443 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1444 * @param[out] buf double buffer to copy data into 1445 * 1446 * @return 0 for success or negative in case of error. 1447 */ 1448 __deprecated 1449 int lwm2m_engine_get_float(const char *pathstr, double *buf); 1450 1451 /** 1452 * @brief Get resource (instance) value (double) 1453 * 1454 * @param[in] path LwM2M path as a struct 1455 * @param[out] value double buffer to copy data into 1456 * 1457 * @return 0 for success or negative in case of error. 1458 */ 1459 int lwm2m_get_f64(const struct lwm2m_obj_path *path, double *value); 1460 1461 /** 1462 * @brief Get resource (instance) value (Objlnk) 1463 * 1464 * @deprecated Use lwm2m_get_objlnk() instead. 1465 * 1466 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1467 * @param[out] buf lwm2m_objlnk buffer to copy data into 1468 * 1469 * @return 0 for success or negative in case of error. 1470 */ 1471 __deprecated 1472 int lwm2m_engine_get_objlnk(const char *pathstr, struct lwm2m_objlnk *buf); 1473 1474 /** 1475 * @brief Get resource (instance) value (Objlnk) 1476 * 1477 * @param[in] path LwM2M path as a struct 1478 * @param[out] buf lwm2m_objlnk buffer to copy data into 1479 * 1480 * @return 0 for success or negative in case of error. 1481 */ 1482 int lwm2m_get_objlnk(const struct lwm2m_obj_path *path, struct lwm2m_objlnk *buf); 1483 1484 /** 1485 * @brief Get resource (instance) value (Time) 1486 * 1487 * @deprecated Use lwm2m_get_time() instead. 1488 * 1489 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1490 * @param[out] buf time_t pointer to copy data 1491 * 1492 * @return 0 for success or negative in case of error. 1493 */ 1494 __deprecated 1495 int lwm2m_engine_get_time(const char *pathstr, time_t *buf); 1496 1497 /** 1498 * @brief Get resource (instance) value (Time) 1499 * 1500 * @param[in] path LwM2M path as a struct 1501 * @param[out] buf time_t pointer to copy data 1502 * 1503 * @return 0 for success or negative in case of error. 1504 */ 1505 int lwm2m_get_time(const struct lwm2m_obj_path *path, time_t *buf); 1506 1507 /** 1508 * @brief Set resource (instance) read callback 1509 * 1510 * @deprecated Use lwm2m_register_read_callback() instead. 1511 * 1512 * LwM2M clients can use this to set the callback function for resource reads when data 1513 * handling in the LwM2M engine needs to be bypassed. 1514 * For example reading back opaque binary data from external storage. 1515 * 1516 * This callback should not generally be used for any data that might be observed as 1517 * engine does not have any knowledge of data changes. 1518 * 1519 * When separate buffer for data should be used, use lwm2m_engine_set_res_buf() instead 1520 * to set the storage. 1521 * 1522 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1523 * @param[in] cb Read resource callback 1524 * 1525 * @return 0 for success or negative in case of error. 1526 */ 1527 __deprecated 1528 int lwm2m_engine_register_read_callback(const char *pathstr, 1529 lwm2m_engine_get_data_cb_t cb); 1530 1531 /** 1532 * @brief Set resource (instance) read callback 1533 * 1534 * LwM2M clients can use this to set the callback function for resource reads when data 1535 * handling in the LwM2M engine needs to be bypassed. 1536 * For example reading back opaque binary data from external storage. 1537 * 1538 * This callback should not generally be used for any data that might be observed as 1539 * engine does not have any knowledge of data changes. 1540 * 1541 * When separate buffer for data should be used, use lwm2m_engine_set_res_buf() instead 1542 * to set the storage. 1543 * 1544 * @param[in] path LwM2M path as a struct 1545 * @param[in] cb Read resource callback 1546 * 1547 * @return 0 for success or negative in case of error. 1548 */ 1549 int lwm2m_register_read_callback(const struct lwm2m_obj_path *path, lwm2m_engine_get_data_cb_t cb); 1550 1551 /** 1552 * @brief Set resource (instance) pre-write callback 1553 * 1554 * @deprecated Use lwm2m_register_pre_write_callback() instead. 1555 * 1556 * This callback is triggered before setting the value of a resource. It 1557 * can pass a special data buffer to the engine so that the actual resource 1558 * value can be calculated later, etc. 1559 * 1560 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1561 * @param[in] cb Pre-write resource callback 1562 * 1563 * @return 0 for success or negative in case of error. 1564 */ 1565 __deprecated 1566 int lwm2m_engine_register_pre_write_callback(const char *pathstr, 1567 lwm2m_engine_get_data_cb_t cb); 1568 1569 /** 1570 * @brief Set resource (instance) pre-write callback 1571 * 1572 * This callback is triggered before setting the value of a resource. It 1573 * can pass a special data buffer to the engine so that the actual resource 1574 * value can be calculated later, etc. 1575 * 1576 * @param[in] path LwM2M path as a struct 1577 * @param[in] cb Pre-write resource callback 1578 * 1579 * @return 0 for success or negative in case of error. 1580 */ 1581 int lwm2m_register_pre_write_callback(const struct lwm2m_obj_path *path, 1582 lwm2m_engine_get_data_cb_t cb); 1583 1584 /** 1585 * @brief Set resource (instance) validation callback 1586 * 1587 * @deprecated Use lwm2m_register_validate_callback() instead. 1588 * 1589 * This callback is triggered before setting the value of a resource to the 1590 * resource data buffer. 1591 * 1592 * The callback allows an LwM2M client or object to validate the data before 1593 * writing and notify an error if the data should be discarded for any reason 1594 * (by returning a negative error code). 1595 * 1596 * @note All resources that have a validation callback registered are initially 1597 * decoded into a temporary validation buffer. Make sure that 1598 * ``CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE`` is large enough to 1599 * store each of the validated resources (individually). 1600 * 1601 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1602 * @param[in] cb Validate resource data callback 1603 * 1604 * @return 0 for success or negative in case of error. 1605 */ 1606 __deprecated 1607 int lwm2m_engine_register_validate_callback(const char *pathstr, 1608 lwm2m_engine_set_data_cb_t cb); 1609 1610 /** 1611 * @brief Set resource (instance) validation callback 1612 * 1613 * This callback is triggered before setting the value of a resource to the 1614 * resource data buffer. 1615 * 1616 * The callback allows an LwM2M client or object to validate the data before 1617 * writing and notify an error if the data should be discarded for any reason 1618 * (by returning a negative error code). 1619 * 1620 * @note All resources that have a validation callback registered are initially 1621 * decoded into a temporary validation buffer. Make sure that 1622 * ``CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE`` is large enough to 1623 * store each of the validated resources (individually). 1624 * 1625 * @param[in] path LwM2M path as a struct 1626 * @param[in] cb Validate resource data callback 1627 * 1628 * @return 0 for success or negative in case of error. 1629 */ 1630 int lwm2m_register_validate_callback(const struct lwm2m_obj_path *path, 1631 lwm2m_engine_set_data_cb_t cb); 1632 1633 /** 1634 * @brief Set resource (instance) post-write callback 1635 * 1636 * @deprecated Use lwm2m_register_post_write_callback() instead. 1637 * 1638 * This callback is triggered after setting the value of a resource to the 1639 * resource data buffer. 1640 * 1641 * It allows an LwM2M client or object to post-process the value of a resource 1642 * or trigger other related resource calculations. 1643 * 1644 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1645 * @param[in] cb Post-write resource callback 1646 * 1647 * @return 0 for success or negative in case of error. 1648 */ 1649 __deprecated 1650 int lwm2m_engine_register_post_write_callback(const char *pathstr, 1651 lwm2m_engine_set_data_cb_t cb); 1652 1653 /** 1654 * @brief Set resource (instance) post-write callback 1655 * 1656 * This callback is triggered after setting the value of a resource to the 1657 * resource data buffer. 1658 * 1659 * It allows an LwM2M client or object to post-process the value of a resource 1660 * or trigger other related resource calculations. 1661 * 1662 * @param[in] path LwM2M path as a struct 1663 * @param[in] cb Post-write resource callback 1664 * 1665 * @return 0 for success or negative in case of error. 1666 */ 1667 int lwm2m_register_post_write_callback(const struct lwm2m_obj_path *path, 1668 lwm2m_engine_set_data_cb_t cb); 1669 1670 /** 1671 * @brief Set resource execute event callback 1672 * 1673 * @deprecated Use lwm2m_register_exec_callback() instead. 1674 * 1675 * This event is triggered when the execute method of a resource is enabled. 1676 * 1677 * @param[in] pathstr LwM2M path string "obj/obj-inst/res" 1678 * @param[in] cb Execute resource callback 1679 * 1680 * @return 0 for success or negative in case of error. 1681 */ 1682 __deprecated 1683 int lwm2m_engine_register_exec_callback(const char *pathstr, 1684 lwm2m_engine_execute_cb_t cb); 1685 1686 /** 1687 * @brief Set resource execute event callback 1688 * 1689 * This event is triggered when the execute method of a resource is enabled. 1690 * 1691 * @param[in] path LwM2M path as a struct 1692 * @param[in] cb Execute resource callback 1693 * 1694 * @return 0 for success or negative in case of error. 1695 */ 1696 int lwm2m_register_exec_callback(const struct lwm2m_obj_path *path, lwm2m_engine_execute_cb_t cb); 1697 1698 /** 1699 * @brief Set object instance create event callback 1700 * 1701 * @deprecated Use lwm2m_register_create_callback instead. 1702 * 1703 * This event is triggered when an object instance is created. 1704 * 1705 * @param[in] obj_id LwM2M object id 1706 * @param[in] cb Create object instance callback 1707 * 1708 * @return 0 for success or negative in case of error. 1709 */ 1710 __deprecated 1711 int lwm2m_engine_register_create_callback(uint16_t obj_id, 1712 lwm2m_engine_user_cb_t cb); 1713 1714 /** 1715 * @brief Set object instance create event callback 1716 * 1717 * This event is triggered when an object instance is created. 1718 * 1719 * @param[in] obj_id LwM2M object id 1720 * @param[in] cb Create object instance callback 1721 * 1722 * @return 0 for success or negative in case of error. 1723 */ 1724 int lwm2m_register_create_callback(uint16_t obj_id, 1725 lwm2m_engine_user_cb_t cb); 1726 1727 /** 1728 * @brief Set object instance delete event callback 1729 * 1730 * @deprecated Use lwm2m_register_delete_callback instead 1731 * 1732 * This event is triggered when an object instance is deleted. 1733 * 1734 * @param[in] obj_id LwM2M object id 1735 * @param[in] cb Delete object instance callback 1736 * 1737 * @return 0 for success or negative in case of error. 1738 */ 1739 __deprecated 1740 int lwm2m_engine_register_delete_callback(uint16_t obj_id, 1741 lwm2m_engine_user_cb_t cb); 1742 1743 /** 1744 * @brief Set object instance delete event callback 1745 * 1746 * This event is triggered when an object instance is deleted. 1747 * 1748 * @param[in] obj_id LwM2M object id 1749 * @param[in] cb Delete object instance callback 1750 * 1751 * @return 0 for success or negative in case of error. 1752 */ 1753 int lwm2m_register_delete_callback(uint16_t obj_id, 1754 lwm2m_engine_user_cb_t cb); 1755 1756 /** 1757 * @brief Resource read-only value bit 1758 */ 1759 #define LWM2M_RES_DATA_READ_ONLY 0 1760 1761 /** 1762 * @brief Resource read-only flag 1763 */ 1764 #define LWM2M_RES_DATA_FLAG_RO BIT(LWM2M_RES_DATA_READ_ONLY) 1765 1766 /** 1767 * @brief Read resource flags helper macro 1768 */ 1769 #define LWM2M_HAS_RES_FLAG(res, f) ((res->data_flags & f) == f) 1770 1771 /** 1772 * @brief Set data buffer for a resource 1773 * 1774 * @deprecated Use lwm2m_set_res_buf() instead. 1775 * 1776 * Use this function to set the data buffer and flags for the specified LwM2M 1777 * resource. 1778 * 1779 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1780 * @param[in] buffer_ptr Data buffer pointer 1781 * @param[in] buffer_len Length of buffer 1782 * @param[in] data_len Length of existing data in the buffer 1783 * @param[in] data_flags Data buffer flags (such as read-only, etc) 1784 * 1785 * @return 0 for success or negative in case of error. 1786 */ 1787 __deprecated 1788 int lwm2m_engine_set_res_buf(const char *pathstr, void *buffer_ptr, uint16_t buffer_len, 1789 uint16_t data_len, uint8_t data_flags); 1790 1791 /** 1792 * @brief Set data buffer for a resource 1793 * 1794 * Use this function to set the data buffer and flags for the specified LwM2M 1795 * resource. 1796 * 1797 * @param[in] path LwM2M path as a struct 1798 * @param[in] buffer_ptr Data buffer pointer 1799 * @param[in] buffer_len Length of buffer 1800 * @param[in] data_len Length of existing data in the buffer 1801 * @param[in] data_flags Data buffer flags (such as read-only, etc) 1802 * 1803 * @return 0 for success or negative in case of error. 1804 */ 1805 int lwm2m_set_res_buf(const struct lwm2m_obj_path *path, void *buffer_ptr, uint16_t buffer_len, 1806 uint16_t data_len, uint8_t data_flags); 1807 1808 /** 1809 * @brief Set data buffer for a resource 1810 * 1811 * Use this function to set the data buffer and flags for the specified LwM2M 1812 * resource. 1813 * 1814 * @deprecated Use lwm2m_set_res_buf() instead, so you can define buffer size and data size 1815 * separately. 1816 * 1817 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1818 * @param[in] data_ptr Data buffer pointer 1819 * @param[in] data_len Length of buffer 1820 * @param[in] data_flags Data buffer flags (such as read-only, etc) 1821 * 1822 * @return 0 for success or negative in case of error. 1823 */ 1824 __deprecated 1825 int lwm2m_engine_set_res_data(const char *pathstr, void *data_ptr, uint16_t data_len, 1826 uint8_t data_flags); 1827 1828 /** 1829 * @brief Update data size for a resource 1830 * 1831 * @deprecated Use lwm2m_set_res_data_len() instead. 1832 * 1833 * Use this function to set the new size of data in the buffer if you write 1834 * to a buffer received by lwm2m_engine_get_res_buf(). 1835 * 1836 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1837 * @param[in] data_len Length of data 1838 * @return 0 for success or negative in case of error. 1839 */ 1840 __deprecated 1841 int lwm2m_engine_set_res_data_len(const char *pathstr, uint16_t data_len); 1842 1843 /** 1844 * @brief Update data size for a resource 1845 * 1846 * Use this function to set the new size of data in the buffer if you write 1847 * to a buffer received by lwm2m_engine_get_res_buf(). 1848 * 1849 * @param[in] path LwM2M path as a struct 1850 * @param[in] data_len Length of data 1851 * @return 0 for success or negative in case of error. 1852 */ 1853 int lwm2m_set_res_data_len(const struct lwm2m_obj_path *path, uint16_t data_len); 1854 1855 /** 1856 * @brief Get data buffer for a resource 1857 * 1858 * @deprecated Use lwm2m_get_res_buf() instead. 1859 * 1860 * Use this function to get the data buffer information for the specified LwM2M 1861 * resource. 1862 * 1863 * If you directly write into the buffer, you must use lwm2m_engine_set_res_data_len() 1864 * function to update the new size of the written data. 1865 * 1866 * All parameters except pathstr can NULL if you don't want to read those values. 1867 * 1868 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1869 * @param[out] buffer_ptr Data buffer pointer 1870 * @param[out] buffer_len Length of buffer 1871 * @param[out] data_len Length of existing data in the buffer 1872 * @param[out] data_flags Data buffer flags (such as read-only, etc) 1873 * 1874 * @return 0 for success or negative in case of error. 1875 */ 1876 __deprecated 1877 int lwm2m_engine_get_res_buf(const char *pathstr, void **buffer_ptr, uint16_t *buffer_len, 1878 uint16_t *data_len, uint8_t *data_flags); 1879 1880 /** 1881 * @brief Get data buffer for a resource 1882 * 1883 * Use this function to get the data buffer information for the specified LwM2M 1884 * resource. 1885 * 1886 * If you directly write into the buffer, you must use lwm2m_set_res_data_len() 1887 * function to update the new size of the written data. 1888 * 1889 * All parameters, except for the pathstr, can be NULL if you don't want to read those values. 1890 * 1891 * @param[in] path LwM2M path as a struct 1892 * @param[out] buffer_ptr Data buffer pointer 1893 * @param[out] buffer_len Length of buffer 1894 * @param[out] data_len Length of existing data in the buffer 1895 * @param[out] data_flags Data buffer flags (such as read-only, etc) 1896 * 1897 * @return 0 for success or negative in case of error. 1898 */ 1899 int lwm2m_get_res_buf(const struct lwm2m_obj_path *path, void **buffer_ptr, uint16_t *buffer_len, 1900 uint16_t *data_len, uint8_t *data_flags); 1901 1902 /** 1903 * @brief Get data buffer for a resource 1904 * 1905 * Use this function to get the data buffer information for the specified LwM2M 1906 * resource. 1907 * 1908 * @deprecated Use lwm2m_get_res_buf() as it can tell you the size of the buffer as well. 1909 * 1910 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)" 1911 * @param[out] data_ptr Data buffer pointer 1912 * @param[out] data_len Length of existing data in the buffer 1913 * @param[out] data_flags Data buffer flags (such as read-only, etc) 1914 * 1915 * @return 0 for success or negative in case of error. 1916 */ 1917 __deprecated 1918 int lwm2m_engine_get_res_data(const char *pathstr, void **data_ptr, uint16_t *data_len, 1919 uint8_t *data_flags); 1920 1921 /** 1922 * @brief Create a resource instance 1923 * 1924 * @deprecated Use lwm2m_create_res_inst() instead. 1925 * 1926 * LwM2M clients use this function to create multi-resource instances: 1927 * Example to create 0 instance of device available power sources: 1928 * lwm2m_engine_create_res_inst("3/0/6/0"); 1929 * 1930 * @param[in] pathstr LwM2M path string "obj/obj-inst/res/res-inst" 1931 * 1932 * @return 0 for success or negative in case of error. 1933 */ 1934 __deprecated 1935 int lwm2m_engine_create_res_inst(const char *pathstr); 1936 1937 /** 1938 * @brief Create a resource instance 1939 * 1940 * LwM2M clients use this function to create multi-resource instances: 1941 * Example to create 0 instance of device available power sources: 1942 * lwm2m_create_res_inst(&LWM2M_OBJ(3, 0, 6, 0)); 1943 * 1944 * @param[in] path LwM2M path as a struct 1945 * 1946 * @return 0 for success or negative in case of error. 1947 */ 1948 int lwm2m_create_res_inst(const struct lwm2m_obj_path *path); 1949 1950 /** 1951 * @brief Delete a resource instance 1952 * 1953 * @deprecated Use lwm2m_delete_res_inst() instead. 1954 * 1955 * Use this function to remove an existing resource instance 1956 * 1957 * @param[in] pathstr LwM2M path string "obj/obj-inst/res/res-inst" 1958 * 1959 * @return 0 for success or negative in case of error. 1960 */ 1961 __deprecated 1962 int lwm2m_engine_delete_res_inst(const char *pathstr); 1963 1964 /** 1965 * @brief Delete a resource instance 1966 * 1967 * Use this function to remove an existing resource instance 1968 * 1969 * @param[in] path LwM2M path as a struct 1970 * 1971 * @return 0 for success or negative in case of error. 1972 */ 1973 int lwm2m_delete_res_inst(const struct lwm2m_obj_path *path); 1974 1975 /** 1976 * @brief Update the period of the device service. 1977 * 1978 * Change the duration of the periodic device service that notifies the 1979 * current time. 1980 * 1981 * @param[in] period_ms New period for the device service (in milliseconds) 1982 * 1983 * @return 0 for success or negative in case of error. 1984 */ 1985 int lwm2m_update_device_service_period(uint32_t period_ms); 1986 1987 /** 1988 * @brief Check whether a path is observed 1989 * 1990 * @deprecated Use lwm2m_path_is_observed() instead. 1991 * 1992 * @param[in] pathstr LwM2M path string to check, e.g. "3/0/1" 1993 * 1994 * @return true when there exists an observation of the same level 1995 * or lower as the given path, false if it doesn't or path is not a 1996 * valid LwM2M-path. 1997 * E.g. true if path refers to a resource and the parent object has an 1998 * observation, false for the inverse. 1999 */ 2000 __deprecated 2001 bool lwm2m_engine_path_is_observed(const char *pathstr); 2002 2003 /** 2004 * @brief Check whether a path is observed 2005 * 2006 * @param[in] path LwM2M path as a struct to check 2007 * 2008 * @return true when there exists an observation of the same level 2009 * or lower as the given path, false if it doesn't or path is not a 2010 * valid LwM2M-path. 2011 * E.g. true if path refers to a resource and the parent object has an 2012 * observation, false for the inverse. 2013 */ 2014 bool lwm2m_path_is_observed(const struct lwm2m_obj_path *path); 2015 2016 /** 2017 * @brief Stop the LwM2M engine 2018 * 2019 * LwM2M clients normally do not need to call this function as it is called 2020 * within lwm2m_rd_client. However, if the client does not use the RD 2021 * client implementation, it will need to be called manually. 2022 * 2023 * @param[in] client_ctx LwM2M context 2024 * 2025 * @return 0 for success or negative in case of error. 2026 */ 2027 int lwm2m_engine_stop(struct lwm2m_ctx *client_ctx); 2028 2029 /** 2030 * @brief Start the LwM2M engine 2031 * 2032 * LwM2M clients normally do not need to call this function as it is called 2033 * by lwm2m_rd_client_start(). However, if the client does not use the RD 2034 * client implementation, it will need to be called manually. 2035 * 2036 * @param[in] client_ctx LwM2M context 2037 * 2038 * @return 0 for success or negative in case of error. 2039 */ 2040 int lwm2m_engine_start(struct lwm2m_ctx *client_ctx); 2041 2042 /** 2043 * @brief Acknowledge the currently processed request with an empty ACK. 2044 * 2045 * LwM2M engine by default sends piggybacked responses for requests. 2046 * This function allows to send an empty ACK for a request earlier (from the 2047 * application callback). The LwM2M engine will then send the actual response 2048 * as a separate CON message after all callbacks are executed. 2049 * 2050 * @param[in] client_ctx LwM2M context 2051 * 2052 */ 2053 void lwm2m_acknowledge(struct lwm2m_ctx *client_ctx); 2054 2055 /** 2056 * @brief LwM2M RD client events 2057 * 2058 * LwM2M client events are passed back to the event_cb function in 2059 * lwm2m_rd_client_start() 2060 */ 2061 enum lwm2m_rd_client_event { 2062 LWM2M_RD_CLIENT_EVENT_NONE, 2063 LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE, 2064 LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE, 2065 LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE, 2066 LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE, 2067 LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE, 2068 LWM2M_RD_CLIENT_EVENT_REG_TIMEOUT, 2069 LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE, 2070 LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE, 2071 LWM2M_RD_CLIENT_EVENT_DISCONNECT, 2072 LWM2M_RD_CLIENT_EVENT_QUEUE_MODE_RX_OFF, 2073 LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED, 2074 LWM2M_RD_CLIENT_EVENT_NETWORK_ERROR, 2075 LWM2M_RD_CLIENT_EVENT_REG_UPDATE, 2076 LWM2M_RD_CLIENT_EVENT_DEREGISTER, 2077 }; 2078 2079 /** 2080 * Define for old event name keeping backward compatibility. 2081 */ 2082 #define LWM2M_RD_CLIENT_EVENT_REG_UPDATE_FAILURE \ 2083 LWM2M_RD_CLIENT_EVENT_REG_TIMEOUT __DEPRECATED_MACRO 2084 2085 /* 2086 * LwM2M RD client flags, used to configure LwM2M session. 2087 */ 2088 2089 /** 2090 * @brief Run bootstrap procedure in current session. 2091 */ 2092 #define LWM2M_RD_CLIENT_FLAG_BOOTSTRAP BIT(0) 2093 2094 /** 2095 * @brief Start the LwM2M RD (Registration / Discovery) Client 2096 * 2097 * The RD client sits just above the LwM2M engine and performs the necessary 2098 * actions to implement the "Registration interface". 2099 * For more information see Section "Client Registration Interface" of 2100 * LwM2M Technical Specification. 2101 * 2102 * NOTE: lwm2m_engine_start() is called automatically by this function. 2103 * 2104 * @param[in] client_ctx LwM2M context 2105 * @param[in] ep_name Registered endpoint name 2106 * @param[in] flags Flags used to configure current LwM2M session. 2107 * @param[in] event_cb Client event callback function 2108 * @param[in] observe_cb Observe callback function called when an observer was 2109 * added or deleted, and when a notification was acked or 2110 * has timed out 2111 * 2112 * @return 0 for success, -EINPROGRESS when client is already running 2113 * or negative error codes in case of failure. 2114 */ 2115 int lwm2m_rd_client_start(struct lwm2m_ctx *client_ctx, const char *ep_name, 2116 uint32_t flags, lwm2m_ctx_event_cb_t event_cb, 2117 lwm2m_observe_cb_t observe_cb); 2118 2119 /** 2120 * @brief Stop the LwM2M RD (De-register) Client 2121 * 2122 * The RD client sits just above the LwM2M engine and performs the necessary 2123 * actions to implement the "Registration interface". 2124 * For more information see Section "Client Registration Interface" of the 2125 * LwM2M Technical Specification. 2126 * 2127 * @param[in] client_ctx LwM2M context 2128 * @param[in] event_cb Client event callback function 2129 * @param[in] deregister True to deregister the client if registered. 2130 * False to force close the connection. 2131 * 2132 * @return 0 for success or negative in case of error. 2133 */ 2134 int lwm2m_rd_client_stop(struct lwm2m_ctx *client_ctx, 2135 lwm2m_ctx_event_cb_t event_cb, bool deregister); 2136 2137 /** 2138 * @brief Suspend the LwM2M engine Thread 2139 * 2140 * Suspend LwM2M engine. Use case could be when network connection is down. 2141 * LwM2M Engine indicate before it suspend by 2142 * LWM2M_RD_CLIENT_EVENT_ENGINE_SUSPENDED event. 2143 * 2144 * @return 0 for success or negative in case of error. 2145 */ 2146 int lwm2m_engine_pause(void); 2147 2148 /** 2149 * @brief Resume the LwM2M engine thread 2150 * 2151 * Resume suspended LwM2M engine. After successful resume call engine will do 2152 * full registration or registration update based on suspended time. 2153 * Event's LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE or LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE 2154 * indicate that client is connected to server. 2155 * 2156 * @return 0 for success or negative in case of error. 2157 */ 2158 int lwm2m_engine_resume(void); 2159 2160 /** 2161 * @brief Trigger a Registration Update of the LwM2M RD Client 2162 */ 2163 void lwm2m_rd_client_update(void); 2164 2165 /** 2166 * @brief LwM2M path maximum length 2167 */ 2168 #define LWM2M_MAX_PATH_STR_SIZE sizeof("/65535/65535/65535/65535") 2169 2170 /** 2171 * @brief Helper function to print path objects' contents to log 2172 * 2173 * @param[in] buf The buffer to use for formatting the string 2174 * @param[in] path The path to stringify 2175 * 2176 * @return Resulting formatted path string 2177 */ 2178 char *lwm2m_path_log_buf(char *buf, struct lwm2m_obj_path *path); 2179 2180 /** 2181 * @brief LwM2M send status 2182 * 2183 * LwM2M send status are generated back to the lwm2m_send_cb_t function in 2184 * lwm2m_send_cb() 2185 */ 2186 enum lwm2m_send_status { 2187 LWM2M_SEND_STATUS_SUCCESS, 2188 LWM2M_SEND_STATUS_FAILURE, 2189 LWM2M_SEND_STATUS_TIMEOUT, 2190 }; 2191 2192 /** 2193 * @typedef lwm2m_send_cb_t 2194 * @brief Callback returning send status 2195 */ 2196 typedef void (*lwm2m_send_cb_t)(enum lwm2m_send_status status); 2197 2198 /** 2199 * @brief LwM2M SEND operation to given path list 2200 * 2201 * @deprecated Use lwm2m_send_cb() instead. 2202 * 2203 * @param ctx LwM2M context 2204 * @param path_list LwM2M Path string list 2205 * @param path_list_size Length of path list. Max size is CONFIG_LWM2M_COMPOSITE_PATH_LIST_SIZE 2206 * @param confirmation_request True request confirmation for operation. 2207 * 2208 * @return 0 for success or negative in case of error. 2209 * 2210 */ 2211 __deprecated 2212 int lwm2m_engine_send(struct lwm2m_ctx *ctx, char const *path_list[], uint8_t path_list_size, 2213 bool confirmation_request); 2214 2215 /** 2216 * @brief LwM2M SEND operation to given path list 2217 * 2218 * @deprecated Use lwm2m_send_cb() instead. 2219 * 2220 * @param ctx LwM2M context 2221 * @param path_list LwM2M path struct list 2222 * @param path_list_size Length of path list. Max size is CONFIG_LWM2M_COMPOSITE_PATH_LIST_SIZE 2223 * @param confirmation_request True request confirmation for operation. 2224 * 2225 * @return 0 for success or negative in case of error. 2226 * 2227 */ 2228 __deprecated 2229 int lwm2m_send(struct lwm2m_ctx *ctx, const struct lwm2m_obj_path path_list[], 2230 uint8_t path_list_size, bool confirmation_request); 2231 2232 /** 2233 * @brief LwM2M SEND operation to given path list asynchronously with confirmation callback 2234 * 2235 * @param ctx LwM2M context 2236 * @param path_list LwM2M path struct list 2237 * @param path_list_size Length of path list. Max size is CONFIG_LWM2M_COMPOSITE_PATH_LIST_SIZE 2238 * @param reply_cb Callback triggered with confirmation state or NULL if not used 2239 * 2240 * @return 0 for success or negative in case of error. 2241 * 2242 */ 2243 int lwm2m_send_cb(struct lwm2m_ctx *ctx, const struct lwm2m_obj_path path_list[], 2244 uint8_t path_list_size, lwm2m_send_cb_t reply_cb); 2245 2246 /** 2247 * @brief Returns LwM2M client context 2248 * 2249 * @return ctx LwM2M context 2250 * 2251 */ 2252 struct lwm2m_ctx *lwm2m_rd_client_ctx(void); 2253 2254 /** 2255 * @brief Enable data cache for a resource. 2256 * 2257 * @deprecated Use lwm2m_enable_cache instead 2258 * 2259 * Application may enable caching of resource data by allocating buffer for LwM2M engine to use. 2260 * Buffer must be size of struct @ref lwm2m_time_series_elem times cache_len 2261 * 2262 * @param resource_path LwM2M resourcepath string "obj/obj-inst/res(/res-inst)" 2263 * @param data_cache Pointer to Data cache array 2264 * @param cache_len number of cached entries 2265 * 2266 * @return 0 for success or negative in case of error. 2267 * 2268 */ 2269 __deprecated 2270 int lwm2m_engine_enable_cache(char const *resource_path, struct lwm2m_time_series_elem *data_cache, 2271 size_t cache_len); 2272 2273 /** 2274 * @brief Enable data cache for a resource. 2275 * 2276 * Application may enable caching of resource data by allocating buffer for LwM2M engine to use. 2277 * Buffer must be size of struct @ref lwm2m_time_series_elem times cache_len 2278 * 2279 * @param path LwM2M path to resource as a struct 2280 * @param data_cache Pointer to Data cache array 2281 * @param cache_len number of cached entries 2282 * 2283 * @return 0 for success or negative in case of error. 2284 * 2285 */ 2286 int lwm2m_enable_cache(const struct lwm2m_obj_path *path, struct lwm2m_time_series_elem *data_cache, 2287 size_t cache_len); 2288 2289 /** 2290 * @brief Security modes as defined in LwM2M Security object. 2291 */ 2292 enum lwm2m_security_mode_e { 2293 LWM2M_SECURITY_PSK = 0, /**< Pre-Shared Key mode */ 2294 LWM2M_SECURITY_RAW_PK = 1, /**< Raw Public Key mode */ 2295 LWM2M_SECURITY_CERT = 2, /**< Certificate mode */ 2296 LWM2M_SECURITY_NOSEC = 3, /**< NoSec mode */ 2297 LWM2M_SECURITY_CERT_EST = 4, /**< Certificate mode with EST */ 2298 }; 2299 2300 /** 2301 * @brief Read security mode from selected security object instance. 2302 * 2303 * This data is valid only if RD client is running. 2304 * 2305 * @param ctx Pointer to client context. 2306 * @return int Positive values are @ref lwm2m_security_mode_e, negative error codes otherwise. 2307 */ 2308 int lwm2m_security_mode(struct lwm2m_ctx *ctx); 2309 2310 /** 2311 * @brief Set default socket options for DTLS connections. 2312 * 2313 * The engine calls this when @ref lwm2m_ctx::set_socketoptions is not overwritten. 2314 * You can call this from the overwritten callback to set extra options after or 2315 * before defaults. 2316 * 2317 * @param ctx Client context 2318 * @return 0 for success or negative in case of error. 2319 */ 2320 int lwm2m_set_default_sockopt(struct lwm2m_ctx *ctx); 2321 2322 #endif /* ZEPHYR_INCLUDE_NET_LWM2M_H_ */ 2323 /**@} */ 2324
