m2mfirmware.h

00001 /*
00002  * Copyright (c) 2015 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef M2MFIRMWARE_H
00017 #define M2MFIRMWARE_H
00018 
00019 #include "mbed-client/m2mobject.h"
00020 
00021 // FORWARD DECLARATION
00022 class M2MResource;
00023 class M2MResourceInstance;
00024 
00025 /*! \file m2mfirmware.h
00026  *  \brief M2MFirmware.
00027  *  This class represents the Firmware Object model of the LWM2M framework.
00028  *  It provides an interface for handling the Firmware Object
00029  *  and all its corresponding resources. There can be only one instance
00030  *  of a Firmware Object.
00031  */
00032 class  M2MFirmware : public M2MObject {
00033 
00034 friend class M2MInterfaceFactory;
00035 
00036 public:
00037 
00038      /**
00039       * \brief An enum defining all the resources associated with a
00040       * Firmware Object in the LWM2M framework.
00041       */
00042     typedef enum {
00043         Package,
00044         PackageUri,
00045         Update,
00046         State,
00047         UpdateSupportedObjects,
00048         UpdateResult,
00049         PackageName,
00050         PackageVersion
00051     } FirmwareResource;
00052 
00053     /**
00054      * \brief An enum defining the state of the firmware update.
00055      */
00056     typedef enum {
00057        Idle = 0,
00058        Downloading,
00059        Downloaded,
00060        Updating
00061     } UpdateState;
00062 
00063     /**
00064      * \brief An enum defining the result of the firmware update.
00065      */
00066     typedef enum {
00067        Default = 0,
00068        SuccessfullyUpdated,
00069        NotEnoughSpace,
00070        OutOfMemory,
00071        ConnectionLost,
00072        CRCCheckFailure,
00073        UnsupportedPackageType,
00074        InvalidURI
00075     } ResultOfUpdate;
00076 
00077 private:
00078 
00079     /**
00080      * Constructor
00081      */
00082     M2MFirmware();
00083 
00084     // Prevents the use of assignment operator.
00085     M2MFirmware& operator=( const M2MFirmware& /*other*/ );
00086 
00087     // Prevents the use of copy constructor.
00088     M2MFirmware( const M2MFirmware& /*other*/ );
00089 
00090     /**
00091      * Destructor
00092      */
00093     virtual ~M2MFirmware();
00094 
00095     static M2MFirmware* get_instance();
00096 
00097 public:
00098 
00099     /**
00100      * \brief Deletes a M2MFirmware instance.
00101      */
00102     static void delete_instance();
00103 
00104     /**
00105      * \brief Creates a new resource for a given resource enum.
00106      * \param resource With this function, the following resources can be created:
00107      * 'PackageUri', 'PackageName','PackageVersion'.
00108      * \param value The value to be set on the resource, in string format.
00109      * \return M2MResource if created successfully, else NULL.
00110      */
00111     M2MResource* create_resource(FirmwareResource resource, const String &value);
00112 
00113     /**
00114      * \brief Creates a new resource for a given resource enum.
00115      * \param resource With this function, the following resources can be created:
00116      * 'State','UpdateSupportedObjects','UpdateResult'.
00117      * \param value The value to be set on the resource, in integer format.
00118      * \return M2MResource if created successfully, else NULL.
00119      */
00120     M2MResource* create_resource(FirmwareResource resource, int64_t value);
00121 
00122     /**
00123      * \brief Deletes a resource with a given resource enum.
00124      * Mandatory resources cannot be deleted.
00125      * \param resource The name of the resource to be deleted.
00126      * \return True if deleted, else false.
00127      */
00128     bool delete_resource(FirmwareResource resource);
00129 
00130     /**
00131      * \brief Sets a value of a given resource enum.
00132      * \param resource With this function, a value can be set on the following resources:
00133      * 'Package', 'PackageUri', 'PackageName','PackageVersion'.
00134      * \param value The value to be set on the resource, in string format.
00135      * \return True if successfully set, else false.
00136      */
00137     bool set_resource_value(FirmwareResource resource,
00138                             const String &value);
00139 
00140     /**
00141      * \brief Sets a value of a given resource enum.
00142      * \param resource With this function, a value can be set for the following resources:
00143      * 'State','UpdateSupportedObjects','UpdateResult'.
00144      * \param value The value to be set on the resource, in integer format.
00145      * \return True if successfully set, else false.
00146      */
00147     bool set_resource_value(FirmwareResource resource,
00148                             int64_t value);
00149 
00150     /**
00151      * \brief Sets a value of a given resource enum.
00152      * \param resource With this function, a value can be set for the following resources:
00153      * 'Package'.
00154      * \param value The value to be set on the resource, in uint8_t format.
00155      * \param size The size of the buffer value to be set on the resource.
00156      * \return True if successfully set, else false.
00157      */
00158     bool set_resource_value(FirmwareResource resource,
00159                             const uint8_t *value,
00160                             const uint32_t length);
00161 
00162     /**
00163      * \brief Returns a value of a given resource enum, in string format.
00164      * \param resource With this function, the following resources can return a value:
00165      * 'PackageUri', 'PackageName','PackageVersion'.
00166      * \return The value associated with that resource, if the key is not valid it returns NULL.
00167      */
00168     String resource_value_string(FirmwareResource resource) const;
00169 
00170     /**
00171      * \brief Returns a value of a given resource key name, in integer format.
00172      * \param resource With this function, the following resources can return a value:
00173      * 'State','UpdateSupportedObjects','UpdateResult'.
00174      * \return The value associated with that resource. If the resource is not valid -1 is returned.
00175      */
00176     int64_t resource_value_int(FirmwareResource resource) const;
00177 
00178     /**
00179      * \brief Populates the data buffer and returns the size of the buffer.
00180      * \param resource With this function, the following resources can return a value:
00181      * 'Package'.
00182      * \param [OUT]data The data buffer containing the value.
00183      * Tha value of the pointer MUST be set as NULL before calling this function unless it has been
00184      * allocated using malloc. In that case the data is freed when calling this function.
00185      * The buffer is allocated using malloc when this function is called and MUST be passed to function free after use.
00186      * \return The size of the buffer populated.
00187      */
00188     uint32_t resource_value_buffer(FirmwareResource resource,
00189                                    uint8_t *&data) const;
00190 
00191     /**
00192      * \brief Returns whether a resource instance with a given resource enum exists or not.
00193      * \param resource The resource enum.
00194      * \return True if at least one instance exists, else false.
00195      */
00196     bool is_resource_present(FirmwareResource resource) const;
00197 
00198     /**
00199      * \brief Returns the number of resources for a whole firmware object.
00200      * \return Total number of resources belonging to the firmware object.
00201      */
00202     uint16_t total_resource_count() const;
00203 
00204     /**
00205      * \brief Returns the number of resources for a given resource enum.
00206      * \param resource The resource enum.
00207      * \return The number of resources for a given resource enum. Returns 1 for the
00208      * mandatory resources. Can be 0 as well if no instances exist for an
00209      * optional resource.
00210      */
00211     uint16_t per_resource_count(FirmwareResource resource) const;
00212 
00213     /**
00214      * \brief Set update resource execute callback function. This is called when update resource
00215      *        receives POST command
00216      * \param callback The function pointer that is called.
00217      * \return True if successfully set, else false.
00218      */
00219     bool set_update_execute_callback(execute_callback callback);
00220 
00221     /**
00222      * \brief Set resource value update callback function. This is called when resource value
00223      *        is updated.
00224      * \param resource The resource enum.
00225      * \param callback The function pointer that is called.
00226      * \return True if successfully set, else false.
00227      */
00228     bool set_resource_value_update_callback(FirmwareResource resource,
00229                                             value_updated_callback callback);
00230 
00231     /**
00232      * \brief Sets the callback function that is executed when this object receives
00233      *        response(Empty ACK) for notification message
00234      * \param resource The resource enum.
00235      * \param callback The function pointer that is called.
00236      * \return True if successfully set, else false.
00237      * \deprecated
00238      */
00239     bool set_resource_notification_sent_callback(FirmwareResource resource,
00240                                                  notification_sent_callback_2 callback) m2m_deprecated;
00241 
00242 
00243     /**
00244      * \brief Sets the callback function that is executed when notification message state changes.
00245      * \param resource The resource enum.
00246      * \param callback The function pointer that is called.
00247      * \return True if successfully set, else false.
00248      */
00249     bool set_resource_notification_sent_callback(FirmwareResource resource,
00250                                                  notification_delivery_status_cb callback);
00251 
00252 #ifndef DISABLE_BLOCK_MESSAGE
00253     /**
00254      * \brief Set incoming_block_message_callback for the package resource.
00255      *        The callback will be called when a block of the package has been received.
00256      * \param callback The function pointer to be called.
00257      * \return true if successfully set, else false.
00258      */
00259     bool set_package_block_message_callback(incoming_block_message_callback callback);
00260 #endif
00261 
00262 private:
00263 
00264     M2MResource* get_resource(FirmwareResource resource) const;
00265 
00266     static const char* resource_name(FirmwareResource resource);
00267 
00268     void create_mandatory_resources();
00269 
00270     bool check_value_range(FirmwareResource resource, const int64_t value) const;
00271 
00272 private :
00273 
00274     M2MObjectInstance*    _firmware_instance;     //Not owned
00275 
00276 protected:
00277 
00278     static M2MFirmware*     _instance;
00279 
00280     friend class Test_M2MFirmware;
00281     friend class Test_M2MInterfaceFactory;
00282 };
00283 
00284 
00285 #endif // M2MFIRMWARE_H