owner-nrf52sdk/nRF5_SDK_15.3.0/components/iot/lwm2m/lwm2m_api.h

/**
 * Copyright (c) 2015 - 2019, Nordic Semiconductor ASA
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, must reproduce the above copyright notice, this list of
 *    conditions and the following disclaimer in the documentation and/or other
 *    materials provided with the distribution.
 *
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 *
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 *
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */
/** @file lwm2m_api.h
*
* @defgroup iot_sdk_lwm2m_api LWM2M Application Programming Interface
* @ingroup iot_sdk_lwm2m
* @{
* @brief Public API of Nordic's LWM2M implementation.
*/
#ifndef LWM2M_API_H__
#define LWM2M_API_H__

#include <stdint.h>

#include "lwm2m.h"

#ifdef __cplusplus
extern "C" {
#endif

/**@addtogroup LWM2M_opcodes Types
 * @{
 * @brief LWMW2M Bootstrap type definitions.
 */

/**@brief LWM2M remote structure type. */
typedef coap_remote_t lwm2m_remote_t;

/**@brief LWM2M time type. */
typedef uint32_t lwm2m_time_t;

/**@brief LWM2M string type. */
typedef struct
{
    char *   p_val;                                /**< Pointer to the value of the string data. */
    uint32_t len;                                  /**< Length of p_val. */
} lwm2m_string_t;

/**@brief LWM2M opaque type. */
typedef struct
{
    uint8_t * p_val;                               /**< Pointer to the value of the opaque data. */
    uint32_t  len;                                 /**< Length of p_val. */
} lwm2m_opaque_t;

/**@brief Application notification callback types. */
typedef enum
{
	LWM2M_NOTIFCATION_TYPE_BOOTSTRAP,		/**< Notification from a bootstrap request. */
	LWM2M_NOTIFCATION_TYPE_REGISTER,		/**< Notification from a register request. */
	LWM2M_NOTIFCATION_TYPE_UPDATE,			/**< Notification from a update request. */
	LWM2M_NOTIFCATION_TYPE_DEREGISTER 		/**< Notification from a deregister request. */
} lwm2m_notification_type_t;

/**@brief LWM2M server configuration type. */
typedef struct
{
	uint32_t 		lifetime;				/** Lifetime parameter **/
	uint64_t 		msisdn;					/** SMS number MSISDN **/
	uint8_t 		lwm2m_version_major;	/** LWM2M major version number **/
	uint8_t 		lwm2m_version_minor;	/** LWM2M miner version number **/
	lwm2m_string_t 	binding;
} lwm2m_server_config_t;

/**@brief LWM2M client identity types. */
typedef enum
{
	LWM2M_CLIENT_ID_TYPE_UUID 	= 36,
	LWM2M_CLIENT_ID_TYPE_IMEI 	= 15,
	LWM2M_CLIENT_ID_TYPE_ESN 	= 8,
	LWM2M_CLIENT_ID_TYPE_MEID 	= 14
} lwm2m_client_identity_type_t;

/**@brief LWM2M identity string.
 *
 * @details Using the string representation of UUID/OPS/OS/IMEI/ESN/MEID.
 *
 * @note: OPS- and OS URN are not currently supported.
 */
typedef union
{
	char 	uuid[36];
	char 	imei[15];
	char 	esn[8];
	char 	meid[14];
} lwm2m_identity_string_t;

/**@brief LWM2M client identity structure type. */
typedef struct
{
	lwm2m_identity_string_t 	 value;
	lwm2m_client_identity_type_t type;
} lwm2m_client_identity_t;
/**@} */

/**@addtogroup LWM2M_defines Defines
 * @{
 * @brief LWMW2M operation code and invalid object/instance definitions.
 */

/**
 * @warning The invalid resource and instance are not stated by the lwm2m spec as reserved and will
 *          cause issues if instances or resources with these IDs is added.
 */
#define LWM2M_NAMED_OBJECT                  65535  /**< Flag to indicate that the object does not use Integer as object id. */
#define LWM2M_INVALID_RESOURCE              65535  /**< Invalid Resource ID. */
#define LWM2M_INVALID_INSTANCE              65535  /**< Invalid Instance ID. */

#define LWM2M_OPERATION_CODE_NONE           0x00   /**< Bit mask for LWM2M no operation. */
#define LWM2M_OPERATION_CODE_READ           0x01   /**< Bit mask for LWM2M read operation. */
#define LWM2M_OPERATION_CODE_WRITE          0x02   /**< Bit mask for LWM2M write operation. */
#define LWM2M_OPERATION_CODE_EXECUTE        0x04   /**< Bit mask for LWM2M execute operation. */
#define LWM2M_OPERATION_CODE_DELETE         0x08   /**< Bit mask for LWM2M delete operation. */
#define LWM2M_OPERATION_CODE_CREATE         0x10   /**< Bit mask for LWM2M create operation. */
#define LWM2M_OPERATION_CODE_DISCOVER       0x20   /**< Bit mask for LWM2M discover operation. */
#define LWM2M_OPERATION_CODE_OBSERVE        0x40   /**< Bit mask for LWM2M observe operation. */
/**@} */

/**@cond */
// Forward declare structs.
typedef struct lwm2m_object_prototype_t   lwm2m_object_prototype_t;
typedef struct lwm2m_instance_prototype_t lwm2m_instance_prototype_t;
/**@endcond */

/**@brief Callback function upon requests on a given LWM2M resource instance.
 *
 * @details Will be called when the request is for an instance Ex. /0/1.
 *
 * If no instance could be located the object callback will be called.
 * The instance_id corresponds to the one in the URI-patch in the CoAP request and may be used to
 * create a new instance. If the value of resource_id is set to LWM2M_INVALID_RESOURCE the callback
 * should treated it as a call to the instance instead of a resource inside of the instance.
 *
 * If a resource has been found p_instance pointer will be set, else it will be NULL.
 *
 * @param[in] p_instance   Pointer to the located resource if it already exists.
 * @param[in] resource_id  Id of the resource requested.
 * @param[in] op_code      Opcode of the request. Values of the opcodes are defined
 *                         in \ref LWM2M_opcodes.
 * @param[in] p_request    Pointer to the CoAP request message.
 *
 * @retval NRF_SUCCESS     Will always return success.
 */
typedef uint32_t (*lwm2m_instance_callback_t)(lwm2m_instance_prototype_t * p_instance,
                                              uint16_t                     resource_id,
                                              uint8_t                      op_code,
                                              coap_message_t *             p_request);

/**@brief Callback function upon request on a given LWM2M object or instance create.
 *
 * @details Will be called when the request is for an object Ex: /0 or /0/1 an instance and the
 *          op_code is CREATE. Depending on the CoAP request code the user might create an instance
 *          or just return the tlv of current instances. If the value of instance_id is set to
 *          LWM2M_INVALID_INSTANCE the callback should treated it as a call to the instance instead
 *          of an instance of the object.
 *
 * @param[in] p_object     Pointer to the located object.
 * @param[in] instance_id  Id of the instance requested.
 * @param[in] op_code      Opcode of the request. Values of the opcodes are defined
 *                         in \ref LWM2M_opcodes.
 * @param[in] p_request    Pointer to the CoAP request message.
 *
 * @retval NRF_SUCCESS     Will always return success.
 */
typedef uint32_t (*lwm2m_object_callback_t)(lwm2m_object_prototype_t * p_object,
                                            uint16_t                   instance_id,
                                            uint8_t                    op_code,
                                            coap_message_t *           p_request);

/**@brief LWM2M object prototype structure.
 *
 * @details Each instance will have this structure in the front of its instance structure.
 *          The object is used to have a common way of looking up its object id and callback
 *          structure for each of the inherited. As there is no instance of the objects themselves,
 *          the prototype is used as a meta object in order to have a common set of functions
 *          for all instances of a object kind.
 */
struct lwm2m_object_prototype_t
{
    uint16_t                        object_id;              /**< Identifies the object. */
    lwm2m_object_callback_t         callback;               /**< Called when for request to /0 (object) and /0/1 if instance 1 is not found. */
    char *                          p_alias_name;           /**< Alternative name of the resource, used when LWM2M_NAMED_OBJECT is set. */
};

/**@brief LWM2M instance structure.
 *
 * @details Prototype for the instance object, this enables us to search through the instances
 *          without knowing the type.
 */
struct lwm2m_instance_prototype_t
{
    uint16_t                        object_id;              /**< Identifies what object this instance belongs to. */
    uint16_t                        instance_id;            /**< Used to identify the instance. */
    uint16_t                        num_resources;          /**< Number of resources MUST equal number of members in the lwm2m instance, sizeof resource_access and sizeof resource_ids. */
    uint8_t                         operations_offset;      /**< Internal use. */
    uint8_t                         resource_ids_offset;    /**< Internal use. */
    lwm2m_instance_callback_t       callback;               /**< Called when an operation is done on this instance. */
};

/**@brief Callback interface from the enabler interface (bootstrap/register) to the application.
 *
 * @warning This is an interface function. MUST BE IMPLEMENTED BY APPLICATION.
 *
 * @param[in] type      Notification type. The types are defined in \ref lwm2m_notification_type_t.
 * @param[in] p_remote  remote that answered the request
 * @param[in] coap_code coap op code from the response
 *
 * @retval NRF_SUCCESS If the client application handled the notification successfully.
 */
uint32_t lwm2m_notification(lwm2m_notification_type_t type,
                            lwm2m_remote_t *          p_remote,
                            uint8_t                   coap_code);

/**@brief CoAP Request handler for the root of the object/instance/resource hierarchy.
 *
 * @details The function is called when a request is for the lwm2m root (ie no object instance
 *          or resource).
 *
 * @warning This is an interface function. MUST BE IMPLEMENTED BY APPLICATION.
 *
 * @param[in]  op_code   LWM2M operation code.
 * @param[in]  p_request Pointer to CoAP request message.
 *
 * @retval     NRF_SUCCESS If the handler processed the request successfully.
 */
uint32_t lwm2m_coap_handler_root(uint8_t op_code, coap_message_t * p_request);

/**@brief Initialize LWM2M library.
 *
 * @retval NRF_SUCCESS If initialization was successful.
 */
uint32_t lwm2m_init(void);

/**@brief Send bootstrap request to a remote bootstrap server.
 *
 * @details Sends a bootstrap request with specified ID to the specified remote, calls the
 *          lwm2m_notification with answer from the bootstrap server.
 *
 * @param[in] p_remote   Pointer to the structure holding connection information of the remote
 *                       LWM2M bootstrap server.
 * @param[in] p_id       Pointer to the structure holding the Id of the client.
 * @param[in] local_port Port number of the local port to be used to send the bootstrap request.
 *
 * @retval NRF_SUCCESS    If bootstrap request to the LWM2M bootstrap server was sent successfully.
 * @retval NRF_ERROR_NULL If one of the parameters was a NULL pointer.
 */
uint32_t lwm2m_bootstrap(lwm2m_remote_t *          p_remote,
                         lwm2m_client_identity_t * p_id,
                         uint16_t                  local_port);

/**@brief Register with a remote LWM2M server.
 *
 * @param[in] p_remote             Pointer to the structure holding connection information
 *                                 of the remote LWM2M server.
 * @param[in] p_id                 Pointer to the structure holding the Id of the client.
 * @param[in] p_config             Registration parameters.
 * @param[in] local_port           Port number of the local port to be used to send the
 *                                 register request.
 * @param[in] p_link_format_string Pointer to a link format encoded string to send in the
 *                                 register request.
 * @param[in] link_format_len      Length of the link format string provided.
 *
 * @retval NRF_SUCCESS If registration request to the LWM2M server was sent out successfully.
 */
uint32_t lwm2m_register(lwm2m_remote_t *          p_remote,
                        lwm2m_client_identity_t * p_id ,
                        lwm2m_server_config_t *   p_config,
                        uint16_t                  local_port,
                        uint8_t *                 p_link_format_string,
                        uint16_t                  link_format_len);

/**@brief Update a registration with a remote server.
 *
 * @param[in] p_remote Pointer to the structure holding connection information of the remote
 *                     LWM2M server.
 * @param[in] p_config Registration parameters.
 * @param[in] local_port Port number of the local port to be used to send the update request.
 *
 * @retval NRF_SUCCESS If update request to the LWM2M server was sent out successfully.
 */
uint32_t lwm2m_update(lwm2m_remote_t *        p_remote,
                      lwm2m_server_config_t * p_config,
                      uint16_t local_port);

/**@brief Deregister from a remote server.
 *
 * @param[in] p_remote Pointer to the structure holding connection information of the remote
 *                     LWM2M server.
 * @param[in] local_port Port number of the local port to be used to send the deregister request.
 *
 * @retval NRF_SUCCESS If deregister request to the LWM2M server was sent out successfully.
 */
uint32_t lwm2m_deregister(lwm2m_remote_t * p_remote, uint16_t local_port);

/**@brief Add an instance to coap_handler in order to match requests to the given instance.
 *
 * @details Add a new LWM2M instance to the coap_handler. The application MUST initialize
 *          and allocate the additional data in the struct.
 *
 * @param[in]  p_instance  Pointer to the instance to add.
 *
 * @retval     NRF_SUCCESS      If registration was successful.
 * @retval     NRF_ERROR_NO_MEM If the module was not able to add the instance. Verify that
 *                              the LWM2M_COAP_HANDLER_MAX_INSTANCES setting in sdk_config.h
 *                              has a correct value.
 */
uint32_t lwm2m_coap_handler_instance_add(lwm2m_instance_prototype_t * p_instance);

/**@brief Delete an instance from coap_handler in order to stop matching requests to the given
 *        instance.
 *
 * @param[in]  p_instance Pointer to the instance to delete.
 *
 * @retval     NRF_SUCCESS         If unregistration was a success.
 * @retval     NRF_ERROR_NOT_FOUND If the given instance was not located.
 */
uint32_t lwm2m_coap_handler_instance_delete(lwm2m_instance_prototype_t * p_instance);

/**@brief Add an object to coap_handler in order to match requests to the given object.
 *
 * @details Add a new LWM2M object to the coap_handler. The application MUST initialize
 *          and allocate the additional data in the struct.
 *
 * @param[in]  p_object  Pointer to the object to add.
 *
 * @retval     NRF_SUCCESS      If registration was successful.
 * @retval     NRF_ERROR_NO_MEM If the module was not able to add the object. Verify that
 *                              the LWM2M_COAP_HANDLER_MAX_OBJECTS setting in sdk_config.h
 *                              has a correct value.
 */
uint32_t lwm2m_coap_handler_object_add(lwm2m_object_prototype_t * p_object);

/**@brief Delete an object from coap_handler in order to stop matching requests to the given
 *        object.
 *
 * @param[in]  p_object Pointer to the object to delete.
 *
 * @retval     NRF_SUCCESS         If unregistration was a success.
 * @retval     NRF_ERROR_NOT_FOUND If the given object was not located.
 */
uint32_t lwm2m_coap_handler_object_delete(lwm2m_object_prototype_t * p_object);

/**@brief Generate link format string based on registered objects and instances.
 *
 * @note For generation of links to work properly it is required that objects is added
 *       before instances.
 *
 * @param[inout] p_buffer     Pointer to a buffer to fill with link format encoded string. If
 *                            a NULL pointer is provided the function will dry-run the function
 *                            in order to calculate how much memory that is needed for the link
 *                            format string.
 * @param[inout] p_buffer_len As input used to indicate the length of the buffer. It will return the
 *                            used amount of buffer length by reference in response. If NULL pointer
 *                            is provided for p_buffer, the value by reference output will be the number
 *                            of bytes needed to generate the link format string.
 *
 * @retval        NRF_SUCCESS      If generation of link format string was successful.
 * @retval        NRF_ERROR_NO_MEM If the provided memory was not large enough.
 */
uint32_t lwm2m_coap_handler_gen_link_format(uint8_t * p_buffer, uint16_t * p_buffer_len);

/**@brief Send CoAP 2.05 Content response with the payload provided.
 *
 * @param[in] p_payload   Pointer to the payload to send. Must not be NULL.
 * @param[in] payload_len Size of the payload.
 * @param[in] p_request   Original CoAP request. Must not be NULL.
 *
 * @retval NRF_SUCCESS If the response was sent out successfully.
 */
uint32_t lwm2m_respond_with_payload(uint8_t *        p_payload,
                                    uint16_t         payload_len,
                                    coap_message_t * p_request);

/**@brief Send CoAP response with a given CoAP message code.
 *
 * @param  [in] code      CoAP response code to send.
 * @param  [in] p_request Original CoAP request. Must not be NULL.
 *
 * @retval NRF_SUCCESS If the response was sent out successfully.
 */
uint32_t lwm2m_respond_with_code(coap_msg_code_t code, coap_message_t * p_request);

#ifdef __cplusplus
}
#endif

#endif // LWM2M_API_H__

/** @} */