427 lines
19 KiB
C
427 lines
19 KiB
C
/**
|
|
* 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__
|
|
|
|
/** @} */
|