#include <MbedCloudClient.h>

Inheritance diagram for MbedCloudClient:

Public Types
enum	Error { ConnectErrorNone = M2MInterface::ErrorNone, ConnectAlreadyExists = M2MInterface::AlreadyExists, ConnectBootstrapFailed = M2MInterface::BootstrapFailed, ConnectInvalidParameters = M2MInterface::InvalidParameters, ConnectNotRegistered = M2MInterface::NotRegistered, ConnectTimeout = M2MInterface::Timeout, ConnectNetworkError = M2MInterface::NetworkError, ConnectResponseParseFailed = M2MInterface::ResponseParseFailed, ConnectUnknownError = M2MInterface::UnknownError, ConnectMemoryConnectFail = M2MInterface::MemoryFail, ConnectNotAllowed = M2MInterface::NotAllowed, ConnectSecureConnectionFailed = M2MInterface::SecureConnectionFailed, ConnectDnsResolvingFailed = M2MInterface::DnsResolvingFailed, ConnectorFailedToStoreCredentials = M2MInterface::FailedToStoreCredentials, ConnectorFailedToReadCredentials = M2MInterface::FailedToReadCredentials, ConnectorInvalidCredentials, UpdateWarningNoActionRequired = UpdateClient::WarningBase, UpdateWarningCertificateNotFound = UpdateClient::WarningCertificateNotFound, UpdateWarningIdentityNotFound = UpdateClient::WarningIdentityNotFound, UpdateWarningVendorMismatch = UpdateClient::WarningVendorMismatch, UpdateWarningClassMismatch = UpdateClient::WarningClassMismatch, UpdateWarningDeviceMismatch = UpdateClient::WarningDeviceMismatch, UpdateWarningCertificateInvalid = UpdateClient::WarningCertificateInvalid, UpdateWarningSignatureInvalid = UpdateClient::WarningSignatureInvalid, UpdateWarningBadKeytable = UpdateClient::WarningBadKeytable, UpdateWarningURINotFound = UpdateClient::WarningURINotFound, UpdateWarningRollbackProtection = UpdateClient::WarningRollbackProtection, UpdateWarningAuthorizationRejected = UpdateClient::WarningAuthorizationRejected, UpdateWarningAuthorizationUnavailable = UpdateClient::WarningAuthorizationUnavailable, UpdateWarningUnknown = UpdateClient::WarningUnknown, UpdateCertificateInsertion = UpdateClient::WarningCertificateInsertion, UpdateErrorUserActionRequired = UpdateClient::ErrorBase, UpdateErrorWriteToStorage = UpdateClient::ErrorWriteToStorage, UpdateErrorInvalidHash = UpdateClient::ErrorInvalidHash, UpdateErrorConnection = UpdateClient::ErrorConnection, UpdateFatalRebootRequired, EnrollmentErrorBase = CE_STATUS_RANGE_BASE, EnrollmentErrorEnd = CE_STATUS_RANGE_END }
	An enum defining different kinds of errors that can occur during various client operations. More...

enum	{ UpdateRequestInvalid = UpdateClient::RequestInvalid, UpdateRequestDownload = UpdateClient::RequestDownload, UpdateRequestInstall = UpdateClient::RequestInstall }
	Enum defining authorization requests from Update Client.

Public Member Functions
	MbedCloudClient ()
	Constructor.

	MbedCloudClient (void(on_registered_cb)(void), void(on_unregistered_cb)(void), void(on_error_cb)(int), void(update_authorize_cb)(int32_t request)=NULL, void(*update_progress_cb)(uint32_t progress, uint32_t total)=NULL)
	Constructor a Cloud Client with given callbacks. More...

virtual	~MbedCloudClient ()
	Destructor.

void	add_objects (const M2MObjectList &object_list)
	Add a list of Objects that the application wants to register to the LwM2M server. This function must be called before calling the `setup()` API. Otherwise, the application gets error `ConnectInvalidParameters`, when calling `setup()`. More...

void	add_objects (const M2MBaseList &base_list)
	Add a list of M2MBase interface implementing objects that the application wants to register to the LwM2M server. This function must be called before calling the `setup()` API. Otherwise, the application gets error `ConnectInvalidParameters`, when calling `setup()`. More...

void	remove_object (M2MBase *object)

void	set_update_callback (MbedCloudClientCallback *callback)
	Set the callback function that is called when there is a new update on any Object/ObjectInstance/Resource from the LwM2M server, typically on receiving `PUT` commands on the registered Objects. More...

bool	init ()
	Initialize the Device Management Client library. More...

bool	setup (void *iface)
	Initiate bootstrapping (first time usage) and register the Device Management Client application to the service. More...

void	on_registered (void(*fn)(void))
	Set the callback function that is called when Device Management Client is registered successfully to Device Management. This is used for a statically defined function. More...

template<typename T >
void	on_registered (T object, void(T::member)(void))
	Set the callback function that is called when Device Management Client is registered successfully to Device Management. This is an overloaded function for a class function. More...

void	on_error (void(*fn)(int))
	Set the callback function that is called when there is any error occuring in the client functionality. The error code can be mapped from the `MbedCloudClient::Error` enum. This is used for a statically defined function. More...

template<typename T >
void	on_error (T object, void(T::member)(int))
	Set the callback function that is called when there is an error occuring in the client functionality. The error code can be mapped from `MbedCloudClient::Error` enum. This is an overloaded function for a class function. More...

void	on_unregistered (void(*fn)(void))
	Set the callback function that is called when Device Management Client is unregistered successfully from Device Management. This is used for a statically defined function. More...

template<typename T >
void	on_unregistered (T object, void(T::member)(void))
	Set the callback function that is called when Device Management Client is unregistered successfully from Device Management. This is an overloaded function for a class function. More...

void	on_registration_updated (void(*fn)(void))
	Set the callback function that is called when Device Management Client registration is updated successfully to Device Management. This is used for a statically defined function. More...

template<typename T >
void	on_registration_updated (T object, void(T::member)(void))
	Set the callback function that is called when Device Management Client registration is updated successfully to Device Management. This is an overloaded function for a class function. More...

void	keep_alive () m2m_deprecated
	Send a registration update message to Device Management when Device Management Client is registered successfully and there is no internal connection error. If Device Management Client is not connected and there is some other internal network transaction ongoing, this function triggers an error `MbedCloudClient::ConnectNotAllowed`. More...

void	register_update ()
	Send a registration update message to Device Management when Device Management Client is registered successfully and there is no internal connection error. If Device Management Client is not connected and there is some other internal network transaction ongoing, this function triggers an error `MbedCloudClient::ConnectNotAllowed`.

void	close ()
	Close the connection towards Device Management and unregister Device Management Client. This function triggers the `on_unregistered()` callback if set by the application.

const ConnectorClientEndpointInfo *	endpoint_info () const
	Return pointer to the `ConnectorClientEndpointInfo` object. More...

void	set_queue_sleep_handler (callback_handler handler)
	Set the function that is called for indicating that Device Management Client is going to sleep when the binding mode is selected with queue mode. More...

void	set_random_number_callback (random_number_cb callback)
	Set the function callback that is called by Device Management Client to fetch a random number from an application to ensure strong entropy. More...

void	set_entropy_callback (entropy_cb callback)
	Set the function callback that is called by Device Management Client to provide an entropy source from an application to ensure strong entropy. More...

void	set_update_authorize_handler (void(*handler)(int32_t request)) __attribute__((deprecated("Use set_update_authorize_priority_handler instead")))
	Register a callback function for authorizing firmware downloads and reboots. More...

void	set_update_authorize_priority_handler (void(*handler)(int32_t request, uint64_t priority))
	Register a callback function for authorizing update requests with priority. More...

void	update_authorize (int32_t request)
	Authorize request passed to authorization handler. More...

void	update_reject (int32_t request, int32_t reason)
	Reject request passed to authorization handler. More...

void	set_update_progress_handler (void(*handler)(uint32_t progress, uint32_t total))
	Register a callback function for monitoring download progress. More...

const char *	error_description () const
	Return error description for the latest error code. More...

void	send_get_request (DownloadType type, const char uri, const size_t offset, get_data_cb data_cb, get_data_error_cb error_cb, void context)
	Send the CoAP `GET` request to the server. The API must be called again with the updated offset to complete the whole transfer. Download type. URI path to the data. Data offset. Callback triggered once there is data available. Callback trigged in case of an error.

ce_status_e	certificate_renew (const char *cert_name)
	Initiate a renewal for a specific certificate. The process will generate new keys in order to create a CSR. The CSR is then sent to the EST service to retrieve the renewed certificate. The new certificate is then safely stored in the device, along with its corresponding private key. More...

void	on_certificate_renewal (cert_renewal_cb_f user_cb)
	Set the callback function that is called when the certificate renewal process has completed. Must be called before any certificate renewal operation. More...

void	pause ()
	Pause Device Management Client's timed functionality and close network connection to Device Management. After a successful call, you can continue the operation by calling `resume()`. More...

void	resume (void *iface)
	Resume Device Management Client's timed functionality and network connection to Device Management. Updates registration. Can be only called after a successful call to `pause()`. More...

est_status_e	est_request_enrollment (const char cert_name, const size_t cert_name_length, uint8_t csr, const size_t csr_length, est_enrollment_result_cb result_cb, void *context) const
	Perform enrollment over secure transport for a certificate signing request. More...

void	est_free_cert_chain_context (cert_chain_context_s *context) const
	Free a certificate chain context structure passed to `est_enrollment_result_cb` callback function. More...

Protected Member Functions
virtual void	complete (ServiceClientCallbackStatus status)
	Indicate that the setup or close operation is complete with success or failure. More...

virtual void	error (int error, const char *reason)
	Indicates an error condition from Device Management Client. More...

virtual void	value_updated (M2MBase *base, M2MBase::BaseType type)
	A callback indicating that the value of the Resource Object is updated by the LwM2M Device Management server. More...

Detailed Description

A High level Cloud Client class.

This is a high level application API that encapsulates and simplifies the usage of LwM2M client. MbedCloudClient internally maintains the M2MInterface which is the main LwM2M client as well as list of LwM2M objects and resources that are registered to the client.

Member Enumeration Documentation

enum MbedCloudClient::Error

An enum defining different kinds of errors that can occur during various client operations.

Range 0x30 - 0x3FF reserved for Connector error.

Enumerator
ConnectErrorNone	No error.
ConnectAlreadyExists	Not used.
ConnectBootstrapFailed	Bootstrap failed. Client recovers automatically.
ConnectInvalidParameters	Security object is not valid or server rejects the registration. No internal recovery mechanism. Actions needed on the application side.
ConnectNotRegistered	Cannot unregister as client is not registered. No internal recovery mechanism. Actions needed on the application side.
ConnectTimeout	Registration has timed out. Client recovers automatically.
ConnectNetworkError	Socket level operation error. Client recovers automatically.
ConnectResponseParseFailed	Failed to parse an incoming CoAP message. Client will continue working, no actions needed.
ConnectUnknownError	Unknown CoAP level error. Client recovers automatically.
ConnectMemoryConnectFail	Memory allocation has failed. No internal recovery mechanism. Actions needed on the application side.
ConnectNotAllowed	API call is not allowed for now. Application should try again later.
ConnectSecureConnectionFailed	Failed to initialize secure connection or DTLS/TLS handshake failed. Client recovers automatically.
ConnectDnsResolvingFailed	DNS resolving has failed. Client recovers automatically.
ConnectorFailedToStoreCredentials	Not used.
ConnectorFailedToReadCredentials	Failed to read credentials from storage. No internal recovery mechanism. Actions needed on the application side.
ConnectorInvalidCredentials	Not used.
EnrollmentErrorBase	Certificate Enrollment error 0x0500 - 0x05ff. Defined in ce_status.h.
EnrollmentErrorEnd	Certificate Enrollment errors end.

Constructor & Destructor Documentation

MbedCloudClient::MbedCloudClient	(	void(*)(void)	on_registered_cb,
		void(*)(void)	on_unregistered_cb,
		void(*)(int)	on_error_cb,
		void(*)(int32_t request)	update_authorize_cb = `NULL`,
		void(*)(uint32_t progress, uint32_t total)	update_progress_cb = `NULL`
	)

Constructor a Cloud Client with given callbacks.

Parameters

on_registered_cb	Callback function that Device Management Client calls when the client has registered successfully to Device Management.
on_unregistered_cb	Callback function that Device Management Client calls when the client has unregistered successfully from Device Management.
on_error_cb	Callback function that Device Management Client calls when there is an error occuring in the client functionality.
on_update_authorize_cb	Callback function that Update Client calls to authorize firmware download or an firmware update.
on_update_progress_cb	Callback function that Update Client calls to report download progress.

Member Function Documentation

void MbedCloudClient::add_objects ( const M2MObjectList & object_list )

Add a list of Objects that the application wants to register to the LwM2M server. This function must be called before calling the setup() API. Otherwise, the application gets error ConnectInvalidParameters, when calling setup().

Parameters

object_list Objects that contain information about Device Management Client attempting to register to the LwM2M server.

void MbedCloudClient::add_objects ( const M2MBaseList & base_list )

Add a list of M2MBase interface implementing objects that the application wants to register to the LwM2M server. This function must be called before calling the setup() API. Otherwise, the application gets error ConnectInvalidParameters, when calling setup().

Parameters

base_list Object implementing the M2MBase interface that contain information about Device Management Client attempting to register to the LwM2M server.

ce_status_e MbedCloudClient::certificate_renew ( const char * cert_name )

Initiate a renewal for a specific certificate. The process will generate new keys in order to create a CSR. The CSR is then sent to the EST service to retrieve the renewed certificate. The new certificate is then safely stored in the device, along with its corresponding private key.

Note: The certificate to be renewed must already exist in the device.

Parameters

cert_name A null terminated C string indicating the name of the certificate to be renewed.

Returns: CE_STATUS_SUCCESS if the asynchronous operation has started successfully. In this case, user callback will be executed at the end of the operation, indicating completion status. If any other ce_status_e:: status is returned - operation encountered an error before the start of the asynchronous stage and user callback will not be executed.

virtual void MbedCloudClient::complete ( ServiceClientCallbackStatus status )

protectedvirtual

Indicate that the setup or close operation is complete with success or failure.

Parameters

status Indicates success or failure in terms of status code.

const ConnectorClientEndpointInfo* MbedCloudClient::endpoint_info ( ) const

Return pointer to the ConnectorClientEndpointInfo object.

Returns: ConnectorClientEndpointInfo pointer.

virtual void MbedCloudClient::error	(	int	error,
		const char *	reason
	)

protectedvirtual

Indicates an error condition from Device Management Client.

Parameters

error	Indicates an error code translated to `MbedCloudClient::Error`.
reason	Indicates human readable text for error description.

const char* MbedCloudClient::error_description ( ) const

Return error description for the latest error code.

Returns: Error description string.

void MbedCloudClient::est_free_cert_chain_context ( cert_chain_context_s * context ) const

Free a certificate chain context structure passed to est_enrollment_result_cb callback function.

Parameters

context Certificate chain context to free.

est_status_e MbedCloudClient::est_request_enrollment	(	const char *	cert_name,
		const size_t	cert_name_length,
		uint8_t *	csr,
		const size_t	csr_length,
		est_enrollment_result_cb	result_cb,
		void *	context
	)		const

Perform enrollment over secure transport for a certificate signing request.

Parameters

cert_name	Name of certificate to enroll.
cert_name_length	Length of certificate name.
csr	Buffer containing the certificate signing request.
csr_length	Length of CSR buffer.
result_cb	Callback function that will be called when the enrollment has completed.
context	Optional pointer to a user context.

bool MbedCloudClient::init ( )

Initialize the Device Management Client library.

If you have not called init() API separately, setup() will call it internally.

You can use this API to ensure two-phased memory allocation for initialization of Device Management Client. This is important in a constrained environment where the network stack or some other component may consume run-time memory before the application calls the setup() API.

Returns: True on success or false in case of failure. False means your application is running low on memory and all APIs, except setup(), will fail with undefined behaviour.

void MbedCloudClient::keep_alive ( )

Send a registration update message to Device Management when Device Management Client is registered successfully and there is no internal connection error. If Device Management Client is not connected and there is some other internal network transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed.

Deprecated:

void MbedCloudClient::on_certificate_renewal ( cert_renewal_cb_f user_cb )

Set the callback function that is called when the certificate renewal process has completed. Must be called before any certificate renewal operation.

Parameters

user_cb Function pointer to the user callback. If user_cb is NULL - no callback is called when the process has completed.

void MbedCloudClient::on_error ( void(*)(int) fn )

Set the callback function that is called when there is any error occuring in the client functionality. The error code can be mapped from the MbedCloudClient::Error enum. This is used for a statically defined function.

Parameters

fn	Function pointer to the function that is called when there is an error in Device Management Client.

template<typename T >

void MbedCloudClient::on_error	(	T *	object,
		void(T::*)(int)	member
	)

Set the callback function that is called when there is an error occuring in the client functionality. The error code can be mapped from MbedCloudClient::Error enum. This is an overloaded function for a class function.

Parameters

object Function pointer to the function that is called when there is an error in Device Management Client.

void MbedCloudClient::on_registered ( void(*)(void) fn )

Set the callback function that is called when Device Management Client is registered successfully to Device Management. This is used for a statically defined function.

Parameters

fn	Function pointer to the function that is called when Device Management Client is registered.

template<typename T >

void MbedCloudClient::on_registered	(	T *	object,
		void(T::*)(void)	member
	)

Set the callback function that is called when Device Management Client is registered successfully to Device Management. This is an overloaded function for a class function.

Parameters

object Function pointer to the function that is called when Device Management Client is registered.

void MbedCloudClient::on_registration_updated ( void(*)(void) fn )

Set the callback function that is called when Device Management Client registration is updated successfully to Device Management. This is used for a statically defined function.

Parameters

fn	Function pointer to the function that is called when Device Management Client registration is updated.

template<typename T >

void MbedCloudClient::on_registration_updated	(	T *	object,
		void(T::*)(void)	member
	)

Set the callback function that is called when Device Management Client registration is updated successfully to Device Management. This is an overloaded function for a class function.

Parameters

object Function pointer to the function that is called when Device Management Client registration is updated.

void MbedCloudClient::on_unregistered ( void(*)(void) fn )

Set the callback function that is called when Device Management Client is unregistered successfully from Device Management. This is used for a statically defined function.

Parameters

fn	Function pointer to the function that is called when Device Management Client is unregistered.

template<typename T >

void MbedCloudClient::on_unregistered	(	T *	object,
		void(T::*)(void)	member
	)

Set the callback function that is called when Device Management Client is unregistered successfully from Device Management. This is an overloaded function for a class function.

Parameters

object Function pointer to the function that is called when Device Management Client is unregistered.

void MbedCloudClient::pause ( )

Pause Device Management Client's timed functionality and close network connection to Device Management. After a successful call, you can continue the operation by calling resume().

Note: This operation does not unregister Device Management Client from Device Management. It closes the socket and removes the interface from the interface list.

void MbedCloudClient::resume ( void * iface )

Resume Device Management Client's timed functionality and network connection to Device Management. Updates registration. Can be only called after a successful call to pause().

Parameters

iface A handler to the network interface.

void MbedCloudClient::set_entropy_callback ( entropy_cb callback )

Set the function callback that is called by Device Management Client to provide an entropy source from an application to ensure strong entropy.

Parameters

entropy_callback Function pointer that is called by Device Management Client while performing a secure handshake. Function signature, if using mbed-client-mbedtls, should be int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len, size_t *olen);.

void MbedCloudClient::set_queue_sleep_handler ( callback_handler handler )

Set the function that is called for indicating that Device Management Client is going to sleep when the binding mode is selected with queue mode.

Parameters

callback Function pointer that is called when Device Management Client goes to sleep.

void MbedCloudClient::set_random_number_callback ( random_number_cb callback )

Set the function callback that is called by Device Management Client to fetch a random number from an application to ensure strong entropy.

Parameters

random_callback Function pointer that is called by Device Management Client while performing a secure handshake. The function signature should be uint32_t (*random_number_callback)(void);.

void MbedCloudClient::set_update_authorize_handler ( void(*)(int32_t request) handler )

Register a callback function for authorizing firmware downloads and reboots.

Parameters

handler Callback function.

void MbedCloudClient::set_update_authorize_priority_handler ( void(*)(int32_t request, uint64_t priority) handler )

Register a callback function for authorizing update requests with priority.

Parameters

handler Callback function.

void MbedCloudClient::set_update_callback ( MbedCloudClientCallback * callback )

Set the callback function that is called when there is a new update on any Object/ObjectInstance/Resource from the LwM2M server, typically on receiving PUT commands on the registered Objects.

Parameters

callback Passes the class Object that implements the callback function to handle the incoming PUT request on a given Object.

void MbedCloudClient::set_update_progress_handler ( void(*)(uint32_t progress, uint32_t total) handler )

Register a callback function for monitoring download progress.

Parameters

handler Callback function.

bool MbedCloudClient::setup ( void * iface )

Initiate bootstrapping (first time usage) and register the Device Management Client application to the service.

If you have not called init() API separately, setup() will call it internally

Parameters

iface A handler to the network interface.

Returns: True on success or false in case of failure. False means your application is running low on memory and all APIs will fail with undefined behaviour. An application using Device Management Client must be able to recover from the failure and retry the initialization of Device Management Client by calling this API or init() at later stage.

void MbedCloudClient::update_authorize ( int32_t request )

Authorize request passed to authorization handler.

Parameters

request Request being authorized.

void MbedCloudClient::update_reject	(	int32_t	request,
		int32_t	reason
	)

Reject request passed to authorization handler.

Parameters

request	Request being rejected.
reason	Reason for rejecting the request.

virtual void MbedCloudClient::value_updated	(	M2MBase *	base,
		M2MBase::BaseType	type
	)

protectedvirtual

A callback indicating that the value of the Resource Object is updated by the LwM2M Device Management server.

Parameters

base	The Object whose value is updated.
type	The type of the Object.

The documentation for this class was generated from the following file:

mbed-cloud-client/mbed-cloud-client/MbedCloudClient.h

Documentation

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation