include/net/lwm2m.h

/*
 * Copyright (c) 2017 Linaro Limited
 * Copyright (c) 2017-2019 Foundries.io
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/** @file lwm2m.h
 *
 * @defgroup lwm2m_api LwM2M high-level API
 * @ingroup networking
 * @{
 * @brief LwM2M high-level API
 *
 * @details
 * LwM2M high-level interface is defined in this header.
 *
 * @note The implementation assumes UDP module is enabled.
 *
 * @note LwM2M 1.0.x is currently the only supported version.
 */

#ifndef ZEPHYR_INCLUDE_NET_LWM2M_H_
#define ZEPHYR_INCLUDE_NET_LWM2M_H_

#include <kernel.h>
#include <sys/mutex.h>
#include <net/coap.h>
#include <net/lwm2m_path.h>

/**
 * @brief LwM2M Objects managed by OMA for LwM2M tech specification.  Objects
 * in this range have IDs from 0 to 1023.
 * For more information refer to Technical Specification
 * OMA-TS-LightweightM2M-V1_0_2-20180209-A
 */

#define LWM2M_OBJECT_SECURITY_ID			0
#define LWM2M_OBJECT_SERVER_ID				1
#define LWM2M_OBJECT_ACCESS_CONTROL_ID			2
#define LWM2M_OBJECT_DEVICE_ID				3
#define LWM2M_OBJECT_CONNECTIVITY_MONITORING_ID		4
#define LWM2M_OBJECT_FIRMWARE_ID			5
#define LWM2M_OBJECT_LOCATION_ID			6
#define LWM2M_OBJECT_CONNECTIVITY_STATISTICS_ID		7

/**
 * @brief LwM2M Objects produced by 3rd party Standards Development
 * Organizations.  Objects in this range have IDs from 2048 to 10240
 * Refer to the OMA LightweightM2M (LwM2M) Object and Resource Registry:
 * http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html
 */

/* clang-format off */
#define IPSO_OBJECT_GENERIC_SENSOR_ID       3300
#define IPSO_OBJECT_TEMP_SENSOR_ID          3303
#define IPSO_OBJECT_HUMIDITY_SENSOR_ID      3304
#define IPSO_OBJECT_LIGHT_CONTROL_ID        3311
#define IPSO_OBJECT_ACCELEROMETER_ID        3313
#define IPSO_OBJECT_PRESSURE_ID             3323
#define IPSO_OBJECT_BUZZER_ID               3338
#define IPSO_OBJECT_TIMER_ID                3340
#define IPSO_OBJECT_ONOFF_SWITCH_ID         3342
#define IPSO_OBJECT_PUSH_BUTTON_ID          3347
/* clang-format on */

typedef void (*lwm2m_socket_fault_cb_t)(int error);
typedef void (*lwm2m_notify_timeout_cb_t)(void);

/**
 * @brief LwM2M context structure to maintain information for a single
 * LwM2M connection.
 */
struct lwm2m_ctx {
	/** Destination address storage */
	struct sockaddr remote_addr;

	/** Private CoAP and networking structures */
	struct coap_pending pendings[CONFIG_LWM2M_ENGINE_MAX_PENDING];
	struct coap_reply replies[CONFIG_LWM2M_ENGINE_MAX_REPLIES];
	sys_slist_t pending_sends;
	sys_slist_t observer;

	/** A pointer to currently processed request, for internal LwM2M engine
	 *  use. The underlying type is ``struct lwm2m_message``, but since it's
	 *  declared in a private header and not exposed to the application,
	 *  it's stored as a void pointer.
	 */
	void *processed_req;

#if defined(CONFIG_LWM2M_DTLS_SUPPORT)
	/** TLS tag is set by client as a reference used when the
	 *  LwM2M engine calls tls_credential_(add|delete)
	 */
	int tls_tag;

	/** Client can set load_credentials function as a way of overriding
	 *  the default behavior of load_tls_credential() in lwm2m_engine.c
	 */
	int (*load_credentials)(struct lwm2m_ctx *client_ctx);
#endif
	/** Flag to indicate if context should use DTLS.
	 *  Enabled via the use of coaps:// protocol prefix in connection
	 *  information.
	 *  NOTE: requires CONFIG_LWM2M_DTLS_SUPPORT=y
	 */
	bool use_dtls;

	/** Current index of Security Object used for server credentials */
	int sec_obj_inst;

	/** Current index of Server Object used in this context. */
	int srv_obj_inst;

	/** Flag to enable BOOTSTRAP interface.  See Section 5.2
	 *  "Bootstrap Interface" of LwM2M Technical Specification 1.0.2
	 *  for more information.
	 */
	bool bootstrap_mode;

	/** Socket File Descriptor */
	int sock_fd;

	/** Socket fault callback. LwM2M processing thread will call this
	 *  callback in case of socket errors on receive.
	 */
	lwm2m_socket_fault_cb_t fault_cb;

	/** Notify Timeout Callback. LwM2M processing thread will call this
	 *  callback in case of notify timeout.
	 */
	lwm2m_notify_timeout_cb_t notify_timeout_cb;

	/** Validation buffer. Used as a temporary buffer to decode the resource
	 *  value before validation. On successful validation, its content is
	 *  copied into the actual resource buffer.
	 */
	uint8_t validate_buf[CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE];
};


/**
 * @brief Asynchronous callback to get a resource buffer and length.
 *
 * Prior to accessing the data buffer of a resource, the engine can
 * use this callback to get the buffer pointer and length instead
 * of using the resource's data buffer.
 *
 * The client or LwM2M objects can register a function of this type via:
 * lwm2m_engine_register_read_callback()
 * lwm2m_engine_register_pre_write_callback()
 *
 * @param[in] obj_inst_id Object instance ID generating the callback.
 * @param[in] res_id Resource ID generating the callback.
 * @param[in] res_inst_id Resource instance ID generating the callback
 *                        (typically 0 for non-multi instance resources).
 * @param[out] data_len Length of the data buffer.
 *
 * @return Callback returns a pointer to the data buffer or NULL for failure.
 */
typedef void *(*lwm2m_engine_get_data_cb_t)(uint16_t obj_inst_id,
					    uint16_t res_id,
					    uint16_t res_inst_id,
					    size_t *data_len);

/**
 * @brief Asynchronous callback when data has been set to a resource buffer.
 *
 * After changing the data of a resource buffer, the LwM2M engine can
 * make use of this callback to pass the data back to the client or LwM2M
 * objects.
 *
 * A function of this type can be registered via:
 * lwm2m_engine_register_validate_callback()
 * lwm2m_engine_register_post_write_callback()
 *
 * @param[in] obj_inst_id Object instance ID generating the callback.
 * @param[in] res_id Resource ID generating the callback.
 * @param[in] res_inst_id Resource instance ID generating the callback
 *                        (typically 0 for non-multi instance resources).
 * @param[in] data Pointer to data.
 * @param[in] data_len Length of the data.
 * @param[in] last_block Flag used during block transfer to indicate the last
 *                       block of data. For non-block transfers this is always
 *                       false.
 * @param[in] total_size Expected total size of data for a block transfer.
 *                       For non-block transfers this is 0.
 *
 * @return Callback returns a negative error code (errno.h) indicating
 *         reason of failure or 0 for success.
 */
typedef int (*lwm2m_engine_set_data_cb_t)(uint16_t obj_inst_id,
					  uint16_t res_id, uint16_t res_inst_id,
					  uint8_t *data, uint16_t data_len,
					  bool last_block, size_t total_size);

/**
 * @brief Asynchronous event notification callback.
 *
 * Various object instance and resource-based events in the LwM2M engine
 * can trigger a callback of this function type: object instance create,
 * and object instance delete.
 *
 * Register a function of this type via:
 * lwm2m_engine_register_create_callback()
 * lwm2m_engine_register_delete_callback()
 *
 * @param[in] obj_inst_id Object instance ID generating the callback.
 *
 * @return Callback returns a negative error code (errno.h) indicating
 *         reason of failure or 0 for success.
 */
typedef int (*lwm2m_engine_user_cb_t)(uint16_t obj_inst_id);

/**
 * @brief Asynchronous execute notification callback.
 *
 * Resource executes trigger a callback of this type.
 *
 * Register a function of this type via:
 * lwm2m_engine_register_exec_callback()
 *
 * @param[in] obj_inst_id Object instance ID generating the callback.
 * @param[in] args Pointer to execute arguments payload. (This can be
 *            NULL if no arguments are provided)
 * @param[in] args_len Length of argument payload in bytes.
 *
 * @return Callback returns a negative error code (errno.h) indicating
 *         reason of failure or 0 for success.
 */
typedef int (*lwm2m_engine_execute_cb_t)(uint16_t obj_inst_id,
					 uint8_t *args, uint16_t args_len);

/**
 * @brief Power source types used for the "Available Power Sources" resource of
 * the LwM2M Device object.
 */
#define LWM2M_DEVICE_PWR_SRC_TYPE_DC_POWER	0
#define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_INT	1
#define LWM2M_DEVICE_PWR_SRC_TYPE_BAT_EXT	2
#define LWM2M_DEVICE_PWR_SRC_TYPE_UNUSED	3
#define LWM2M_DEVICE_PWR_SRC_TYPE_PWR_OVER_ETH	4
#define LWM2M_DEVICE_PWR_SRC_TYPE_USB		5
#define LWM2M_DEVICE_PWR_SRC_TYPE_AC_POWER	6
#define LWM2M_DEVICE_PWR_SRC_TYPE_SOLAR		7
#define LWM2M_DEVICE_PWR_SRC_TYPE_MAX		8

/**
 * @brief Error codes used for the "Error Code" resource of the LwM2M Device
 * object.  An LwM2M client can register one of the following error codes via
 * the lwm2m_device_add_err() function.
 */
#define LWM2M_DEVICE_ERROR_NONE			0
#define LWM2M_DEVICE_ERROR_LOW_POWER		1
#define LWM2M_DEVICE_ERROR_EXT_POWER_SUPPLY_OFF	2
#define LWM2M_DEVICE_ERROR_GPS_FAILURE		3
#define LWM2M_DEVICE_ERROR_LOW_SIGNAL_STRENGTH	4
#define LWM2M_DEVICE_ERROR_OUT_OF_MEMORY	5
#define LWM2M_DEVICE_ERROR_SMS_FAILURE		6
#define LWM2M_DEVICE_ERROR_NETWORK_FAILURE	7
#define LWM2M_DEVICE_ERROR_PERIPHERAL_FAILURE	8

/**
 * @brief Battery status codes used for the "Battery Status" resource (3/0/20)
 *        of the LwM2M Device object.  As the battery status changes, an LwM2M
 *        client can set one of the following codes via:
 *        lwm2m_engine_set_u8("3/0/20", [battery status])
 */
#define LWM2M_DEVICE_BATTERY_STATUS_NORMAL	0
#define LWM2M_DEVICE_BATTERY_STATUS_CHARGING	1
#define LWM2M_DEVICE_BATTERY_STATUS_CHARGE_COMP	2
#define LWM2M_DEVICE_BATTERY_STATUS_DAMAGED	3
#define LWM2M_DEVICE_BATTERY_STATUS_LOW		4
#define LWM2M_DEVICE_BATTERY_STATUS_NOT_INST	5
#define LWM2M_DEVICE_BATTERY_STATUS_UNKNOWN	6

/**
 * @brief Register a new error code with LwM2M Device object.
 *
 * @param[in] error_code New error code.
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_device_add_err(uint8_t error_code);


/**
 * @brief LWM2M Firmware Update object states
 *
 * An LwM2M client or the LwM2M Firmware Update object use the following codes
 * to represent the LwM2M Firmware Update state (5/0/3).
 */
#define STATE_IDLE		0
#define STATE_DOWNLOADING	1
#define STATE_DOWNLOADED	2
#define STATE_UPDATING		3

/**
 * @brief LWM2M Firmware Update object result codes
 *
 * After processing a firmware update, the client sets the result via one of
 * the following codes via lwm2m_engine_set_u8("5/0/5", [result code])
 */
#define RESULT_DEFAULT		0
#define RESULT_SUCCESS		1
#define RESULT_NO_STORAGE	2
#define RESULT_OUT_OF_MEM	3
#define RESULT_CONNECTION_LOST	4
#define RESULT_INTEGRITY_FAILED	5
#define RESULT_UNSUP_FW		6
#define RESULT_INVALID_URI	7
#define RESULT_UPDATE_FAILED	8
#define RESULT_UNSUP_PROTO	9

#if defined(CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT)
/**
 * @brief Set data callback for firmware block transfer.
 *
 * LwM2M clients use this function to register a callback for receiving the
 * block transfer data when performing a firmware update.
 *
 * @param[in] cb A callback function to receive the block transfer data
 */
void lwm2m_firmware_set_write_cb(lwm2m_engine_set_data_cb_t cb);

/**
 * @brief Get the data callback for firmware block transfer writes.
 *
 * @return A registered callback function to receive the block transfer data
 */
lwm2m_engine_set_data_cb_t lwm2m_firmware_get_write_cb(void);

#if defined(CONFIG_LWM2M_FIRMWARE_UPDATE_PULL_SUPPORT)
/**
 * @brief Set data callback to handle firmware update execute events.
 *
 * LwM2M clients use this function to register a callback for receiving the
 * update resource "execute" operation on the LwM2M Firmware Update object.
 *
 * @param[in] cb A callback function to receive the execute event.
 */
void lwm2m_firmware_set_update_cb(lwm2m_engine_execute_cb_t cb);

/**
 * @brief Get the event callback for firmware update execute events.
 *
 * @return A registered callback function to receive the execute event.
 */
lwm2m_engine_execute_cb_t lwm2m_firmware_get_update_cb(void);

/**
 * @brief Get the block context of the current firmware block.
 *
 * @param[out] ctx A buffer to store the block context.
 */
struct coap_block_context *lwm2m_firmware_get_block_context();
#endif
#endif

/**
 * @brief Maximum value for ObjLnk resource fields
 */
#define LWM2M_OBJLNK_MAX_ID USHRT_MAX

/**
 * @brief LWM2M ObjLnk resource type structure
 */
struct lwm2m_objlnk {
	uint16_t obj_id;
	uint16_t obj_inst;
};

/**
 * @brief Change an observer's pmin value.
 *
 * LwM2M clients use this function to modify the pmin attribute
 * for an observation being made.
 * Example to update the pmin of a temperature sensor value being observed:
 * lwm2m_engine_update_observer_min_period("3303/0/5700",5);
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res"
 * @param[in] period_s Value of pmin to be given (in seconds).
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_update_observer_min_period(char *pathstr, uint32_t period_s);

/**
 * @brief Change an observer's pmax value.
 *
 * LwM2M clients use this function to modify the pmax attribute
 * for an observation being made.
 * Example to update the pmax of a temperature sensor value being observed:
 * lwm2m_engine_update_observer_max_period("3303/0/5700",5);
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res"
 * @param[in] period_s Value of pmax to be given (in seconds).
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_update_observer_max_period(char *pathstr, uint32_t period_s);

/**
 * @brief Create an LwM2M object instance.
 *
 * LwM2M clients use this function to create non-default LwM2M objects:
 * Example to create first temperature sensor object:
 * lwm2m_engine_create_obj_inst("3303/0");
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst"
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_create_obj_inst(char *pathstr);

/**
 * @brief Delete an LwM2M object instance.
 *
 * LwM2M clients use this function to delete LwM2M objects.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst"
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_delete_obj_inst(char *pathstr);

/**
 * @brief Set resource (instance) value (opaque buffer)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] data_ptr Data buffer
 * @param[in] data_len Length of buffer
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_opaque(char *pathstr, char *data_ptr, uint16_t data_len);

/**
 * @brief Set resource (instance) value (string)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] data_ptr NULL terminated char buffer
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_string(char *pathstr, char *data_ptr);

/**
 * @brief Set resource (instance) value (u8)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value u8 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_u8(char *pathstr, uint8_t value);

/**
 * @brief Set resource (instance) value (u16)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value u16 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_u16(char *pathstr, uint16_t value);

/**
 * @brief Set resource (instance) value (u32)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value u32 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_u32(char *pathstr, uint32_t value);

/**
 * @brief Set resource (instance) value (u64)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value u64 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_u64(char *pathstr, uint64_t value);

/**
 * @brief Set resource (instance) value (s8)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value s8 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_s8(char *pathstr, int8_t value);

/**
 * @brief Set resource (instance) value (s16)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value s16 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_s16(char *pathstr, int16_t value);

/**
 * @brief Set resource (instance) value (s32)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value s32 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_s32(char *pathstr, int32_t value);

/**
 * @brief Set resource (instance) value (s64)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value s64 value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_s64(char *pathstr, int64_t value);

/**
 * @brief Set resource (instance) value (bool)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value bool value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_bool(char *pathstr, bool value);

/**
 * @brief Set resource (instance) value (double)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value double value
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_float(char *pathstr, double *value);

/**
 * @brief Set resource (instance) value (ObjLnk)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] value pointer to the lwm2m_objlnk structure
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_objlnk(char *pathstr, struct lwm2m_objlnk *value);

/**
 * @brief Get resource (instance) value (opaque buffer)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] buf Data buffer to copy data into
 * @param[in] buflen Length of buffer
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_opaque(char *pathstr, void *buf, uint16_t buflen);

/**
 * @brief Get resource (instance) value (string)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] str String buffer to copy data into
 * @param[in] strlen Length of buffer
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_string(char *pathstr, void *str, uint16_t strlen);

/**
 * @brief Get resource (instance) value (u8)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value u8 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_u8(char *pathstr, uint8_t *value);

/**
 * @brief Get resource (instance) value (u16)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value u16 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_u16(char *pathstr, uint16_t *value);

/**
 * @brief Get resource (instance) value (u32)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value u32 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_u32(char *pathstr, uint32_t *value);

/**
 * @brief Get resource (instance) value (u64)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value u64 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_u64(char *pathstr, uint64_t *value);

/**
 * @brief Get resource (instance) value (s8)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value s8 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_s8(char *pathstr, int8_t *value);

/**
 * @brief Get resource (instance) value (s16)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value s16 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_s16(char *pathstr, int16_t *value);

/**
 * @brief Get resource (instance) value (s32)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value s32 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_s32(char *pathstr, int32_t *value);

/**
 * @brief Get resource (instance) value (s64)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value s64 buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_s64(char *pathstr, int64_t *value);

/**
 * @brief Get resource (instance) value (bool)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] value bool buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_bool(char *pathstr, bool *value);

/**
 * @brief Get resource (instance) value (double)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] buf double buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_float(char *pathstr, double *buf);

/**
 * @brief Get resource (instance) value (ObjLnk)
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] buf lwm2m_objlnk buffer to copy data into
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_objlnk(char *pathstr, struct lwm2m_objlnk *buf);


/**
 * @brief Set resource (instance) read callback
 *
 * LwM2M clients can use this to set the callback function for resource reads.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] cb Read resource callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_read_callback(char *pathstr,
					lwm2m_engine_get_data_cb_t cb);

/**
 * @brief Set resource (instance) pre-write callback
 *
 * This callback is triggered before setting the value of a resource.  It
 * can pass a special data buffer to the engine so that the actual resource
 * value can be calculated later, etc.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] cb Pre-write resource callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_pre_write_callback(char *pathstr,
					     lwm2m_engine_get_data_cb_t cb);

/**
 * @brief Set resource (instance) validation callback
 *
 * This callback is triggered before setting the value of a resource to the
 * resource data buffer.
 *
 * The callback allows an LwM2M client or object to validate the data before
 * writing and notify an error if the data should be discarded for any reason
 * (by returning a negative error code).
 *
 * @note All resources that have a validation callback registered are initially
 *       decoded into a temporary validation buffer. Make sure that
 *       ``CONFIG_LWM2M_ENGINE_VALIDATION_BUFFER_SIZE`` is large enough to
 *       store each of the validated resources (individually).
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] cb Validate resource data callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_validate_callback(char *pathstr,
					    lwm2m_engine_set_data_cb_t cb);

/**
 * @brief Set resource (instance) post-write callback
 *
 * This callback is triggered after setting the value of a resource to the
 * resource data buffer.
 *
 * It allows an LwM2M client or object to post-process the value of a resource
 * or trigger other related resource calculations.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] cb Post-write resource callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_post_write_callback(char *pathstr,
					      lwm2m_engine_set_data_cb_t cb);

/**
 * @brief Set resource execute event callback
 *
 * This event is triggered when the execute method of a resource is enabled.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res"
 * @param[in] cb Execute resource callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_exec_callback(char *pathstr,
					lwm2m_engine_execute_cb_t cb);

/**
 * @brief Set object instance create event callback
 *
 * This event is triggered when an object instance is created.
 *
 * @param[in] obj_id LwM2M object id
 * @param[in] cb Create object instance callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_create_callback(uint16_t obj_id,
					  lwm2m_engine_user_cb_t cb);

/**
 * @brief Set object instance delete event callback
 *
 * This event is triggered when an object instance is deleted.
 *
 * @param[in] obj_id LwM2M object id
 * @param[in] cb Delete object instance callback
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_register_delete_callback(uint16_t obj_id,
					  lwm2m_engine_user_cb_t cb);

/**
 * @brief Resource read-only value bit
 */
#define LWM2M_RES_DATA_READ_ONLY	0

/**
 * @brief Resource read-only flag
 */
#define LWM2M_RES_DATA_FLAG_RO		BIT(LWM2M_RES_DATA_READ_ONLY)

/**
 * @brief Read resource flags helper macro
 */
#define LWM2M_HAS_RES_FLAG(res, f)	((res->data_flags & f) == f)

/**
 * @brief Set data buffer for a resource
 *
 * Use this function to set the data buffer and flags for the specified LwM2M
 * resource.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[in] data_ptr Data buffer pointer
 * @param[in] data_len Length of buffer
 * @param[in] data_flags Data buffer flags (such as read-only, etc)
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_set_res_data(char *pathstr, void *data_ptr, uint16_t data_len,
			      uint8_t data_flags);

/**
 * @brief Get data buffer for a resource
 *
 * Use this function to get the data buffer information for the specified LwM2M
 * resource.
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res(/res-inst)"
 * @param[out] data_ptr Data buffer pointer
 * @param[out] data_len Length of buffer
 * @param[out] data_flags Data buffer flags (such as read-only, etc)
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_get_res_data(char *pathstr, void **data_ptr,
			      uint16_t *data_len, uint8_t *data_flags);

/**
 * @brief Create a resource instance
 *
 * LwM2M clients use this function to create multi-resource instances:
 * Example to create 0 instance of device available power sources:
 * lwm2m_engine_create_res_inst("3/0/6/0");
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res/res-inst"
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_create_res_inst(char *pathstr);

/**
 * @brief Delete a resource instance
 *
 * Use this function to remove an existing resource instance
 *
 * @param[in] pathstr LwM2M path string "obj/obj-inst/res/res-inst"
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_delete_res_inst(char *pathstr);

/**
 * @brief Update the period of a given service.
 *
 * Allow the period modification on an existing service created with
 * lwm2m_engine_add_service().
 * Example to frequency at which a periodic_service changes it's values :
 * lwm2m_engine_update_service(device_periodic_service,5*MSEC_PER_SEC);
 *
 * @param[in] service Handler of the periodic_service
 * @param[in] period_ms New period for the periodic_service (in milliseconds)
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_update_service_period(k_work_handler_t service, uint32_t period_ms);

/**
 * @brief Update the period of the device service.
 *
 * Change the duration of the periodic device service that notifies the
 * current time.
 *
 * @param[in] period_ms New period for the device service (in milliseconds)
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_update_device_service_period(uint32_t period_ms);

/**
 * @brief Start the LwM2M engine
 *
 * LwM2M clients normally do not need to call this function as it is called
 * by lwm2m_rd_client_start().  However, if the client does not use the RD
 * client implementation, it will need to be called manually.
 *
 * @param[in] client_ctx LwM2M context
 *
 * @return 0 for success or negative in case of error.
 */
int lwm2m_engine_start(struct lwm2m_ctx *client_ctx);

/**
 * @brief Acknowledge the currently processed request with an empty ACK.
 *
 * LwM2M engine by default sends piggybacked responses for requests.
 * This function allows to send an empty ACK for a request earlier (from the
 * application callback). The LwM2M engine will then send the actual response
 * as a separate CON message after all callbacks are executed.
 *
 * @param[in] client_ctx LwM2M context
 *
 */
void lwm2m_acknowledge(struct lwm2m_ctx *client_ctx);

/**
 * @brief LwM2M RD client events
 *
 * LwM2M client events are passed back to the event_cb function in
 * lwm2m_rd_client_start()
 */
enum lwm2m_rd_client_event {
	LWM2M_RD_CLIENT_EVENT_NONE,
	LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_FAILURE,
	LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE,
	LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE,
	LWM2M_RD_CLIENT_EVENT_REGISTRATION_FAILURE,
	LWM2M_RD_CLIENT_EVENT_REGISTRATION_COMPLETE,
	LWM2M_RD_CLIENT_EVENT_REG_UPDATE_FAILURE,
	LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE,
	LWM2M_RD_CLIENT_EVENT_DEREGISTER_FAILURE,
	LWM2M_RD_CLIENT_EVENT_DISCONNECT,
	LWM2M_RD_CLIENT_EVENT_QUEUE_MODE_RX_OFF,
	LWM2M_RD_CLIENT_EVENT_NETWORK_ERROR,
};

/*
 * LwM2M RD client flags, used to configure LwM2M session.
 */

/**
 * @brief Run bootstrap procedure in current session.
 */
#define LWM2M_RD_CLIENT_FLAG_BOOTSTRAP BIT(0)

/**
 * @brief Asynchronous RD client event callback
 *
 * @param[in] ctx LwM2M context generating the event
 * @param[in] event LwM2M RD client event code
 */
typedef void (*lwm2m_ctx_event_cb_t)(struct lwm2m_ctx *ctx,
				     enum lwm2m_rd_client_event event);

/**
 * @brief Start the LwM2M RD (Registration / Discovery) Client
 *
 * The RD client sits just above the LwM2M engine and performs the necessary
 * actions to implement the "Registration interface".
 * For more information see Section 5.3 "Client Registration Interface" of the
 * LwM2M Technical Specification.
 *
 * NOTE: lwm2m_engine_start() is called automatically by this function.
 *
 * @param[in] client_ctx LwM2M context
 * @param[in] ep_name Registered endpoint name
 * @param[in] flags Flags used to configure current LwM2M session.
 * @param[in] event_cb Client event callback function
 */
void lwm2m_rd_client_start(struct lwm2m_ctx *client_ctx, const char *ep_name,
			   uint32_t flags, lwm2m_ctx_event_cb_t event_cb);

/**
 * @brief Stop the LwM2M RD (De-register) Client
 *
 * The RD client sits just above the LwM2M engine and performs the necessary
 * actions to implement the "Registration interface".
 * For more information see Section 5.3 "Client Registration Interface" of the
 * LwM2M Technical Specification.
 *
 * @param[in] client_ctx LwM2M context
 * @param[in] event_cb Client event callback function
 * @param[in] deregister True to deregister the client if registered.
 *                       False to force close the connection.
 */
void lwm2m_rd_client_stop(struct lwm2m_ctx *client_ctx,
			  lwm2m_ctx_event_cb_t event_cb, bool deregister);

/**
 * @brief Trigger a Registration Update of the LwM2M RD Client
 */
void lwm2m_rd_client_update(void);

#endif	/* ZEPHYR_INCLUDE_NET_LWM2M_H_ */
/**@}  */