/*
 *
 *    Copyright (c) 2013-2017 Nest Labs, Inc.
 *    All rights reserved.
 *
 *    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.
 */

/**
 *    @file
 *      This file defines message descriptions for the messages in
 *      the software update profile.
 *
 *      The profile has a client and server role. the basic protocol
 *      can be diagrammed as follows:
 *
 *
 *          | Server |                    | Client |
 *          ----------------------------------------
 *          ImageAnnounce--------------->
 *                 <----------------------ImageQuery
 *          ImageQueryResponse---------->
 *                                        (Client downloads firmware image)
 *                 <----------------------DownloadNotify
 *          NotifyReponse--------------->
 *                                        (Client updates its firmware)
 *                 <----------------------UpdateNotify
 *          NotifyReponse--------------->
 *
 *      where the image announce message is optional.
 *
 */

#ifndef _SW_UPDATE_PROFILE_H
#define _SW_UPDATE_PROFILE_H

#include <Weave/Support/NLDLLUtil.h>

/**
 *   @namespace nl::Weave::Profiles::SoftwareUpdate
 *
 *   @brief
 *     This namespace includes all interfaces within Weave for the
 *     Weave Software Update profile, which includes the
 *     corresponding, protocol of the same name.
 */

namespace nl {
namespace Weave {
namespace Profiles {
namespace SoftwareUpdate {
  /*
   * the protocol spelled out in the profile specification comprises
   * 7 messages as described above. the image announce is optional.
   * the message type identifiers for these messages are as follows:
   */
  enum {
    kMsgType_ImageAnnounce =			0,
    kMsgType_ImageQuery = 				1,
    kMsgType_ImageQueryResponse = 		2,
    kMsgType_DownloadNotify = 			3,
    kMsgType_NotifyRepsponse = 			4, //FIXME: check the spelling!
    kMsgType_UpdateNotify =				5,
    kMsgType_ImageQueryStatus =			6, // in case the image query fails
  };
  /*
   * the software update profile defines a number of profile-specific status
   * codes.
   *
   * - kStatus_NoUpdateAvailable: server => client, indicates that an
   * image query has been recieved and understood and that the server has no
   * update for the client at this time.
   *
   * - kStatus_UpdateFailed: client => server, indicates that an attempt
   * to install an image specified by the server has failed.
   *
   * - kStatus_InvalidInstructions: client => server, indicates that
   * the client was unable to download an image because the download
   * instructions contained in the ImageQueryResponse, i.e. URI, update scheme,
   * update condition, were poorly formed or inconsistent.
   *
   * - kStatus_DownloadFailed: client => server, indicates that an
   * attempted download failed.
   *
   * - kStatus_IntegrityCheckFailed: client => server, indicates that
   * an image was downloaded but it failed the subsequent integrity check.
   *
   * - kStatus_Abort: server => client, indicates that the client
   * should give up since the server is out of options.
   *
   * - kStatus_Retry: srever => client, indicates that the client
   * should submit another image query and restart/continue the update
   * process.
   */
  enum {
    kStatus_NoUpdateAvailable =			0x0001,
    kStatus_UpdateFailed =			0x0010,
    kStatus_InvalidInstructions =		0x0050,
    kStatus_DownloadFailed =			0x0051,
    kStatus_IntegrityCheckFailed =		0x0052,
    kStatus_Abort =				0x0053,
    kStatus_Retry =				0x0091,
  };
  /*
   * the frame control field of the image query frame has the following
   * control flags
   */
  enum {
    kFlag_PackageSpecPresent =                  1,
    kFlag_LocaleSpecPresent =                   2,
    kFlag_TargetNodeIdPresent =                 4,
  };
  /*
   * the (optional) update options field of the image query response (IQR) frame
   * defines a set of bitmasks.
   */
  enum {
    kMask_UpdatePriority =			0x03, // 0b00000011
    kMask_UpdateCondition =			0x1C, // 0b00011100
    kMask_ReportStatus =			0x20, // 0b00100000
  };
  /*
   * and shift offsets
   */
  enum {
    kOffset_UpdatePriority =                    0,
    kOffset_UpdateCondition =                   2,
    kOffset_ReportStatus =                      5,
  };
  /*
   * the image query frame contains information about which integrity checking
   * the client supports and the image query response contains an integrity type
   * and value for the image that the client is being instructed to download and
   * install. the supported types are:
   */
  enum {
    kIntegrityType_SHA160 = 			0, // 160-bit Secure Hash, aka SHA-1, required
    kIntegrityType_SHA256 =				1, // 256-bit Secure Hash (SHA-2)
    kIntegrityType_SHA512 =				2, // 512-bit, Secure Hash (SHA-2)
  };
  /*
   * the lengths in bytes for the integrity specification byte-strings are as follows.
   */
  enum {
    kLength_SHA160 =					20,
    kLength_SHA256 =					32,
    kLength_SHA512 =					64,
  };
  /*
   * similarly, the image query contains information about which update
   * schemes, i.e. download protocols, the client supports, and the response
   * contains a value for indicating the update scheme to use in downloading
   * the images. the supported schemes are:
   */
  enum {
    kUpdateScheme_HTTP =				0,
    kUpdateScheme_HTTPS	=				1,
    kUpdateScheme_SFTP =				2,
    kUpdateScheme_BDX =					3, // Nest Weave download protocol
  };

  /*
   * Data Element Tags for the Software Update Profile
   */
  enum
  {
    // ---- Top-level Tags ----
    //                                   Tag Type        Element Type      Disposition
    //                                   ----------------------------------------------
    kTag_InstalledLocales       = 0x00,    // Fully-Qualified  Array of strings   Required
    kTag_CertBodyId             = 0x01,    // Fully-Qualified  Integer            Required
    kTag_WirelessRegDom         = 0x02,    // Fully-Qualified  Integer            Optional
    kTag_SufficientBatterySWU   = 0x03     // Fully-Qualified  Bool               Required
  };


  /*
   * on the air and over the wire, the image announce looks like.
   *
   * | <Weave version> (==0) | <message type> (==0) | <exchange id> |
   * | <profile id> (==0x0000000C) |
   *
   * that is, it's a bare Weave application header with profile ID 0x0000000C
   * and message type 1. the structure provided here is not really used
   * except as a placeholder.
   */
  class ImageAnnounce { };
  /*
   * the image query frame has the following form.
   *
   * | <frame control> | <product specification> | <vendor specific data> (optional) |
   * | <version specification> | <locale specification> (optional) |
   * | <integrity type list> | <update scheme list > |
   *
   * where the frame control field has bit-fields as follows:
   * bit 0 - 1==vendor-specifc data present, 0==not present
   * bit 1 - 1==locale specification present, 0==not present
   *
   * the image query, as a structure reads slightly differently from the in-flight
   * representation. in particular, the version and locale are null-terminated
   * strings and both of the optional items are represented as nullable pointers
   * so there isn't a separate boolean to check.
   *
   * here's an auxiliary class that holds a list of integrity types as part of
   * the image query. these are pretty simple and are essentially wrappers
   * around a 3-element array of values drawn from the above enumeration.
   */
  class NL_DLL_EXPORT IntegrityTypeList {
  public:
    // constructor
    IntegrityTypeList();
    // initializer
    WEAVE_ERROR init(uint8_t, uint8_t*);
    // packing and parsing
    WEAVE_ERROR pack(MessageIterator&);
    uint16_t packedLength();
    static WEAVE_ERROR parse(MessageIterator&, IntegrityTypeList&);
    // comparison
    bool operator == (const IntegrityTypeList&) const;
    // this is just a short list with specified length. if length is
    // 0 this indicates that the list is undefined since, to be useful,
    // one of these things has to caontain at least one element.
    uint8_t theLength;
    uint8_t theList[3];
  };
  /*
   * an auxiliary class that holds a list of update schemes as part of
   * the image query. these are pretty simple and are essenitlly wrappers
   * around a 4-element array of values drawn from the above enumeration.
   */
  class NL_DLL_EXPORT UpdateSchemeList {
  public:
    // constructor
    UpdateSchemeList();
    // initializer
    WEAVE_ERROR init(uint8_t, uint8_t*);
    // packing and parsing
    WEAVE_ERROR pack(MessageIterator&);
    uint16_t packedLength();
    static WEAVE_ERROR parse(MessageIterator&, UpdateSchemeList&);
    // comparison
    bool operator == (const UpdateSchemeList&) const;
    // data members
    // this is just a short list with specified length. if length is
    // 0 this indicates that the list is undefined since, to be useful,
    // one of these things has to caontain at least one element.
    uint8_t theLength;
    uint8_t theList[4];
  };
  /*
   * an auxiliary class that represents a product specification, which
   * for our purposes will consist of:
   * - a 16-bit vendor identifer
   * - a 16-bit product identifier
   * - a 16-bit porduct revision number
   */
  class NL_DLL_EXPORT ProductSpec {
  public:
    // constructors
    ProductSpec(uint16_t, uint16_t, uint16_t);
    ProductSpec();
    // comparison
    bool operator == (const ProductSpec&) const;

    // data members
    uint16_t vendorId;
    uint16_t productId;
    uint16_t productRev;
  };
  /*
   * ImageQuery also declares a utility print method but obviously this
   * can only be defined is there's some way to do printing, e.g. on a test
   * platform or framework.
   */
  class NL_DLL_EXPORT ImageQuery {
  public:
    // constructor
    ImageQuery();
    // initializer
    WEAVE_ERROR init(ProductSpec &aProductSpec,
                     ReferencedString &aVersion, // 1 byte length
                     IntegrityTypeList &aTypeList,
                     UpdateSchemeList &aSchemeList,
                     ReferencedString *aPackage=NULL, // 1 byte length
                     ReferencedString *aLocale=NULL,
                     uint64_t aTargetNodeId=0,
                     ReferencedTLVData *aMetaData=NULL); // 2 byte length
    // packing and parsing
    WEAVE_ERROR pack(PacketBuffer*);
    uint16_t packedLength();
    static WEAVE_ERROR parse(PacketBuffer*, ImageQuery&);
    // comparison
    bool operator == (const ImageQuery&) const;
    // utility
    void print(void);
    // data members
    ProductSpec productSpec;
    ReferencedString version;
    IntegrityTypeList integrityTypes;
    UpdateSchemeList updateSchemes;
    uint64_t targetNodeId;
    ReferencedString packageSpec;	// optional
    ReferencedString localeSpec;		// optional
    ReferencedTLVData theMetaData;	// optional
  };
  /*
   * the image query response message has the form:
   *
   * | <status report> | URI (optional) | | <version specification> (optional) |
   * | <integrity specification> (optional) | <update scheme> (optional) |
   * | <update options> (optional) |
   *
   * where all the the fields following the status report field are optional and
   * have values of significance only if the status report denotes success.
   *
   * the format of the (optional) update options field is as follows:
   *
   * |      b0...b2           b3...b4              b5        b6...b7 |
   * | <update priority> <update condition> <report status> reserved |
   *
   * there are only two update priorities:
   */
  enum UpdatePriority {
    Normal, 		// updated may be execute at leisure
    Critical, 	// update must be executed immediately
  };
  /*
   * there are 4 conditions governing update:
   *
   * - IfUnmatched, download and install the image if the version
   * specification in the response frame doesn't match the software version
   * currently installed.
   *
   * - IfLater, download and install the image if the version specification
   * in the response frame is later than the software version currently
   * installed.
   *
   * - Unconditionally, download and install the image, don't ask questions,
   * don't pass go, don't collect $200.
   *
   * - OnOptIn, download and install the image on some trigger provided
   * by an on-site user.
   */
  enum UpdateCondition {
    IfUnmatched,
    IfLater,
    Unconditionally,
    OnOptIn
  };
  /*
   * an integrity specification is a simple object that contains an
   * integrity type, as defined in the above enumeration, plus an integrity
   * check value.
   *
   * and the integrity specification object itself is sized to fit
   * the largest of these.
   */
  class NL_DLL_EXPORT IntegritySpec {
  public:
    //constructor
    IntegritySpec();
    // initializer
    WEAVE_ERROR init(uint8_t, uint8_t*);
    // packing and parsing
    WEAVE_ERROR pack(MessageIterator&);
    static WEAVE_ERROR parse(MessageIterator&, IntegritySpec&);
    // comparison
    bool operator == (const IntegritySpec&) const;
    // data members
    uint8_t type;
    uint8_t value[64];
  };
  /*
   * the image query response is only sent in the case where
   * the image query is processed successfully and produces an
   * image to download. it eszentially constitues download instructions
   * for the node the submitted the query.
   */
  class NL_DLL_EXPORT ImageQueryResponse {
  public:
    // constructor
    ImageQueryResponse();
    // initializers
    WEAVE_ERROR init (ReferencedString&, ReferencedString&, IntegritySpec&, uint8_t, UpdatePriority, UpdateCondition, bool);
    // packing and parsing
    WEAVE_ERROR pack(PacketBuffer*);
    uint16_t packedLength();
    static WEAVE_ERROR parse(PacketBuffer*, ImageQueryResponse&);
    // comparison
    bool operator == (const ImageQueryResponse&) const;
    // utility
    void print(void);
    // data members
    ReferencedString uri;
    ReferencedString versionSpec;
    IntegritySpec integritySpec;
    uint8_t updateScheme;
    UpdatePriority updatePriority;
    UpdateCondition updateCondition;
    bool reportStatus;
  };
} // namespace SoftwareUpdate
} // namespace Profiles
} // namespace Weave
} // namespace nl
#endif // _SW_UPDATE_PROFILE_H