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 /**
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 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 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 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 the M2MFirmware instance.
00101      */
00102     static void delete_instance();
00103 
00104     /**
00105      * \brief Creates a new resource for 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 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 the resource with the 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 the value of the 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 the value of the 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 the value of the 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 the value of the given resource enum, in String.
00164      * \param resource With this function, the following resources can return value:
00165      * 'PackageUri', 'PackageName','PackageVersion'.
00166      * \return The value associated with that resource, if key is not valid it returns NULL.
00167      */
00168     String resource_value_string(FirmwareResource resource) const;
00169 
00170     /**
00171      * \brief Returns the value of the given resource key name, in Integer.
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      * \return The size of the buffer populated.
00184      */
00185     uint32_t resource_value_buffer(FirmwareResource resource,
00186                                    uint8_t *&data) const;
00187 
00188     /**
00189      * \brief Returns whether the resource instance with given resource enum exists or not.
00190      * \param resource Resource enum.
00191      * \return True if at least one instance exists, else false.
00192      */
00193     bool is_resource_present(FirmwareResource resource) const;
00194 
00195     /**
00196      * \brief Returns the number of resources for the whole firmware object.
00197      * \return Total number of resources belonging to the firmware object.
00198      */
00199     uint16_t total_resource_count() const;
00200 
00201     /**
00202      * \brief Returns the number of resources for a given resource enum.
00203      * \param resource Resource enum.
00204      * \return The number of resources for a given resource enum. Returns 1 for the
00205      * mandatory resources. Can be 0 as well if no instance exists for an
00206      * optional resource.
00207      */
00208     uint16_t per_resource_count(FirmwareResource resource) const;
00209 
00210 
00211 private:
00212 
00213     M2MResource* get_resource(FirmwareResource resource) const;
00214 
00215     static const String resource_name(FirmwareResource resource);
00216 
00217     void create_mandatory_resources();
00218 
00219     bool check_value_range(FirmwareResource resource, const int64_t value) const;
00220 
00221     void set_zero_value(M2MResource *resource);
00222 
00223 private :
00224 
00225     M2MObjectInstance*    _firmware_instance;     //Not owned
00226 
00227 protected:
00228 
00229     static M2MFirmware*     _instance;
00230 
00231     friend class Test_M2MFirmware;
00232     friend class Test_M2MInterfaceFactory;
00233 };
00234 
00235 
00236 #endif // M2MFIRMWARE_H