Mistake on this page? Email us

#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

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_cbCallback function that Device Management Client calls when the client has registered successfully to Device Management.
on_unregistered_cbCallback function that Device Management Client calls when the client has unregistered successfully from Device Management.
on_error_cbCallback function that Device Management Client calls when there is an error occuring in the client functionality.
on_update_authorize_cbCallback function that Update Client calls to authorize firmware download or an firmware update.
on_update_progress_cbCallback 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_listObjects 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_listObject 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_nameA 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
statusIndicates 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
errorIndicates an error code translated to MbedCloudClient::Error.
reasonIndicates 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
contextCertificate 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_nameName of certificate to enroll.
cert_name_lengthLength of certificate name.
csrBuffer containing the certificate signing request.
csr_lengthLength of CSR buffer.
result_cbCallback function that will be called when the enrollment has completed.
contextOptional 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_cbFunction 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
fnFunction 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
objectFunction 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
fnFunction 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
objectFunction 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
fnFunction 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
objectFunction 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
fnFunction 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
objectFunction 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
ifaceA 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_callbackFunction 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
callbackFunction 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_callbackFunction 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
handlerCallback 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
handlerCallback 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
callbackPasses 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
handlerCallback 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
ifaceA 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
requestRequest being authorized.
void MbedCloudClient::update_reject ( int32_t  request,
int32_t  reason 
)

Reject request passed to authorization handler.

Parameters
requestRequest being rejected.
reasonReason 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
baseThe Object whose value is updated.
typeThe type of the Object.

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