MbedCloudClient.h

Go to the documentation of this file.

// ----------------------------------------------------------------------------
// Copyright 2016-2019 ARM Ltd.
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------------------------------------------------------


#ifndef __MBED_CLOUD_CLIENT_H__
#define __MBED_CLOUD_CLIENT_H__

#include "include/ServiceClient.h"
#ifndef MBED_CLIENT_DISABLE_EST_FEATURE
#include "est_defs.h"
#endif // !MBED_CLIENT_DISABLE_EST_FEATURE
#include "mbed-cloud-client/MbedCloudClientConfig.h"

#ifndef MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
// This overly long path is needed to have build compatibility with previous
// version. A #include can't just point to a file which is not in application's
// include path and we should not force application to add every internal directory
// of MCC to their paths.
// On next phase, the cmake is used to publish the API paths via
// target_include_directories(), but that requires a bit more cleanups.
#include "certificate-enrollment-client/certificate-enrollment-client/ce_defs.h"
#endif // MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT

#if MBED_CLOUD_CLIENT_STL_API
#include <map>
#include <string>
#include <vector>
#endif

#if MBED_CLOUD_CLIENT_STD_NAMESPACE_POLLUTION
// We should not really pollute application's namespace with std:: by having this in
// a public header file.
// But as as removal of the next line may break existing applications, which build due to this
// leakage, we need to maintain the old behavior for a while and just allow one to remove it.
using namespace std;
#endif

class SimpleM2MResourceBase;

class MbedCloudClientCallback {

public:

    virtual void value_updated(M2MBase *base, M2MBase::BaseType type) = 0;
};



class MbedCloudClient : public ServiceClientCallback {

public:

    typedef enum {
        // Range 0x30 - 0x3FF reserved for Connector error.
        ConnectErrorNone                        = M2MInterface::ErrorNone,

        // Not used.
        ConnectAlreadyExists                    = M2MInterface::AlreadyExists,

        // Bootstrap failed.
        // Client recovers automatically.
        ConnectBootstrapFailed                  = M2MInterface::BootstrapFailed,

        // Security object is not valid or server rejects the registration.
        // No internal recovery mechanism. Actions needed on the application side.
        ConnectInvalidParameters                = M2MInterface::InvalidParameters,

        // Cannot unregister as client is not registered.
        // No internal recovery mechanism. Actions needed on the application side.
        ConnectNotRegistered                    = M2MInterface::NotRegistered,

        // Registration has timed out.
        // Client recovers automatically.
        ConnectTimeout                          = M2MInterface::Timeout,

        // Socket level operation error.
        // Client recovers automatically.
        ConnectNetworkError                     = M2MInterface::NetworkError,

        // Failed to parse an incoming CoAP message.
        // Client will continue working, no actions needed.
        ConnectResponseParseFailed              = M2MInterface::ResponseParseFailed,

        // Unknown CoAP level error.
        // Client recovers automatically.
        ConnectUnknownError                     = M2MInterface::UnknownError,

        // Memory allocation has failed.
        // No internal recovery mechanism. Actions needed on the application side.
        ConnectMemoryConnectFail                = M2MInterface::MemoryFail,

        // API call is not allowed for now.
        // Application should try again later.
        ConnectNotAllowed                       = M2MInterface::NotAllowed,

        // Failed to initialize secure connection or DTLS/TLS handshake failed.
        // Client recovers automatically.
        ConnectSecureConnectionFailed           = M2MInterface::SecureConnectionFailed,

        // DNS resolving has failed.
        // Client recovers automatically.
        ConnectDnsResolvingFailed               = M2MInterface::DnsResolvingFailed,

        // Not used.
        ConnectorFailedToStoreCredentials       = M2MInterface::FailedToStoreCredentials,

        // Failed to read credentials from storage.
        // No internal recovery mechanism. Actions needed on the application side.
        ConnectorFailedToReadCredentials        = M2MInterface::FailedToReadCredentials,

        // Not used.
        ConnectorInvalidCredentials,
#ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
        UpdateWarningNoActionRequired           = UpdateClient::WarningBase, // Range reserved for Update Error from 0x0400 - 0x04FF
        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,
#endif
#ifndef MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
        // Certificate Enrollment error 0x0500 - 0x05ff. Defined in ce_status.h
        EnrollmentErrorBase = CE_STATUS_RANGE_BASE,
        EnrollmentErrorEnd = CE_STATUS_RANGE_END
#endif // MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
    }Error;

#ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE

    enum {
        UpdateRequestInvalid                    = UpdateClient::RequestInvalid,
        UpdateRequestDownload                   = UpdateClient::RequestDownload,
        UpdateRequestInstall                    = UpdateClient::RequestInstall
    };
#endif

    MbedCloudClient();

    MbedCloudClient(void(*on_registered_cb)(void),
                    void(*on_unregistered_cb)(void),
                    void(*on_error_cb)(int)
#ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
                    ,void(*update_authorize_cb)(int32_t request) = NULL,
                    void(*update_progress_cb)(uint32_t progress, uint32_t total) = NULL
#endif
                   );

    virtual ~MbedCloudClient();

    void add_objects(const M2MObjectList& object_list);

    void add_objects(const M2MBaseList& base_list);

    void remove_object(M2MBase *object);

    void set_update_callback(MbedCloudClientCallback *callback);

    bool init();

    bool setup(void* iface);

    void on_registered(void(*fn)(void));

    template<typename T>
    void on_registered(T *object, void (T::*member)(void));

    void on_error(void(*fn)(int));

    template<typename T>
    void on_error(T *object, void (T::*member)(int));

    void on_unregistered(void(*fn)(void));

    template<typename T>
    void on_unregistered(T *object, void (T::*member)(void));

    void on_registration_updated(void(*fn)(void));

    template<typename T>
        void on_registration_updated(T *object, void (T::*member)(void));

    void keep_alive() m2m_deprecated;

    void register_update();

    void close();

    const ConnectorClientEndpointInfo *endpoint_info() const;

    void set_queue_sleep_handler(callback_handler handler);

    void set_random_number_callback(random_number_cb callback);

    void set_entropy_callback(entropy_cb callback);

#if MBED_CLOUD_CLIENT_STL_API

    bool set_device_resource_value(M2MDevice::DeviceResource resource,
                                   const std::string &value) m2m_deprecated;
#endif

#ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE

    void set_update_authorize_handler(void (*handler)(int32_t request));

    void set_update_authorize_priority_handler(void (*handler)(int32_t request, uint64_t priority));

    void update_authorize(int32_t request);

    void update_reject(int32_t request, int32_t reason);

    void set_update_progress_handler(void (*handler)(uint32_t progress, uint32_t total));
#endif

    const char *error_description() const;

    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);

#ifndef MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT

    ce_status_e certificate_renew(const char *cert_name);

    void on_certificate_renewal(cert_renewal_cb_f user_cb);
#endif // MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT

#ifdef MBED_CLOUD_CLIENT_EDGE_EXTENSION

    const M2MBaseList *get_object_list() const;
#endif // MBED_CLOUD_CLIENT_EDGE_EXTENSION

    void pause();

    void resume(void *iface);

#ifndef MBED_CLIENT_DISABLE_EST_FEATURE

    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;

    void est_free_cert_chain_context(cert_chain_context_s *context) const;
#endif // !MBED_CLIENT_DISABLE_EST_FEATURE

protected: // from ServiceClientCallback

    virtual void complete(ServiceClientCallbackStatus status);

    virtual void error(int error, const char *reason);

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

private:

#if MBED_CLOUD_CLIENT_STL_API
    void register_update_callback(string route, SimpleM2MResourceBase* resource) m2m_deprecated;
#endif

private:

    ServiceClient                                   _client;
    MbedCloudClientCallback                         *_value_callback;
    M2MBaseList                                     _object_list;
    FP0<void>                                       _on_registered;
    FP0<void>                                       _on_unregistered;
    FP0<void>                                       _on_registration_updated;
    FP1<void,int>                                   _on_error;
    const char                                      *_error_description;
    bool                                            _init_done;

#if MBED_CLOUD_CLIENT_STL_API
    // This API and functionality is being phased out, as it is wasting resources by
    // duplicating data and harming portability by requiring an STL implementation.
    map<string, M2MObject*>                         _objects;
    map<string, M2MResource*>                       _resources;
    map<string, SimpleM2MResourceBase*>             _update_values;

friend class SimpleM2MResourceBase;

#endif // MBED_CLOUD_CLIENT_STL_API
};

template<typename T>
void MbedCloudClient::on_registered(T *object, void (T::*member)(void))
{
    FP0<void> fp(object, member);
    _on_registered = fp;
}

template<typename T>
void MbedCloudClient::on_error(T *object, void (T::*member)(int))
{
    FP1<void, int> fp(object, member);
    _on_error = fp;
}

template<typename T>
void MbedCloudClient::on_unregistered(T *object, void (T::*member)(void))
{
    FP0<void> fp(object, member);
    _on_unregistered = fp;
}

template<typename T>
void MbedCloudClient::on_registration_updated(T *object, void (T::*member)(void))
{
    FP0<void> fp(object, member);
    _on_registration_updated = fp;
}
#endif // __MBED_CLOUD_CLIENT_H__