/*
 *
 *    Copyright (c) 2015-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
 *
 *  @brief
 *   Definitions for the abstract ProfileDatabase auxiliary class.
 *
 *  This file contains definitions for the abstract ProfileDatabase
 *  auxiliary class, which is intended to make the construction of
 *  WDM-based applications more straightforward by providing a template
 *  and filling common infrastructure. Also provided is a set of helper
 *  functions for wrangling WDM-related TLV.
 */

#ifndef _WEAVE_DATA_MANAGEMENT_PROFILE_DATABASE_LEGACY_H
#define _WEAVE_DATA_MANAGEMENT_PROFILE_DATABASE_LEGACY_H

#include <Weave/Profiles/data-management/Legacy/WdmManagedNamespace.h>

#include <Weave/Profiles/data-management/DataManagement.h>

namespace nl {
namespace Weave {
namespace Profiles {
namespace WeaveMakeManagedNamespaceIdentifier(DataManagement, kWeaveManagedNamespaceDesignation_Legacy) {

    /**
     *  @brief
     *    Start writing a path list.
     *
     *  Write the TLV for the beginning of a WDM path list, e.g. as
     *  the primary argument of a ViewRequest().
     *
     *  @param [in]     aWriter         A reference to a TLV writer
     *                                  with which to start writing.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to start a container.
     */

    static inline WEAVE_ERROR StartPathList(nl::Weave::TLV::TLVWriter &aWriter)
    {
        nl::Weave::TLV::TLVType pathListContainer;

        return aWriter.StartContainer(nl::Weave::TLV::ProfileTag(kWeaveProfile_WDM, kTag_WDMPathList),
                                      nl::Weave::TLV::kTLVType_Array, pathListContainer);
    };


    /**
     *  @brief
     *    Start writing a data list.
     *
     *  Write the TLV for the beginning of a WDM data list, e.g. as
     *  the primary argument of an UpdateRequest().
     *
     *  @param [in]     aWriter         A reference to a TLV writer
     *                                  with which to start writing.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to start a container.
     */

    static inline WEAVE_ERROR StartDataList(nl::Weave::TLV::TLVWriter &aWriter)
    {
        nl::Weave::TLV::TLVType dataListContainer;

        return aWriter.StartContainer(nl::Weave::TLV::ProfileTag(kWeaveProfile_WDM, kTag_WDMDataList),
                                      nl::Weave::TLV::kTLVType_Array, dataListContainer);
    };

    /**
     *  @brief
     *    Start writing a data list to a given ReferencedTLVData object.
     *
     *  Write the TLV for the beginning of a WDM data list. In this
     *  case, we assume that we're writing out the data list to a
     *  referenced TLV data structure. The writer is assumed to be
     *  uninitialized - or, in any case, will be initialized to point
     *  to the given object.
     *
     *  @param [out]    aDataList       A reference to a
     *                                  ReferencedTLVData object that
     *                                  is to be the target of the
     *                                  writer and eventually contain
     *                                  the data of interest.
     *
     *  @param [in]     aWriter         A reference to a TLV writer
     *                                  with which to start writing.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to start a container.
     */

    static inline WEAVE_ERROR StartDataList(ReferencedTLVData &aDataList, nl::Weave::TLV::TLVWriter &aWriter)
    {
        aWriter.Init(aDataList.theData, aDataList.theMaxLength);

        return StartDataList(aWriter);
    };

    /**
     *  @brief
     *    Finish writing a path list or data list.
     *
     *  Write the TLV for the end of a WDM path or data list. Also,
     *  finalize the writer.
     *
     *  @param [in,out] aWriter         A reference to a TLV writer
     *                                  with which to write the end of
     *                                  the list.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to end a container.
     */

    static inline WEAVE_ERROR EndList(nl::Weave::TLV::TLVWriter &aWriter)
    {
        WEAVE_ERROR err = WEAVE_NO_ERROR;

        /*
         * in the normal case, which is what these convenience methods
         * are attempting to address, both the path list and data list
         * appear as the only elements of a top-level TLV
         * structure. thus, the outer container type is always
         * "structure".
         */

        err = aWriter.EndContainer(nl::Weave::TLV::kTLVType_Structure);
        if (err == WEAVE_NO_ERROR)
        {
            err = aWriter.Finalize();
        }

        return err;
    };

    /**
     *  @brief
     *    Finish writing a path list or data list.
     *
     *  Write the TLV for the end of a WDM path or data list. Also,
     *  finalize the writer. In this case, the ReferencedTLVData object
     *  to which the TLV is being written is passed in and modified to
     *  reflect the amount of data written.
     *
     *  @param [in,out] aList           A reference to the
     *                                  ReferenceTLVData object to
     *                                  which the list was being
     *                                  written.
     *
     *  @param [in]     aWriter         A reference to a TLV writer
     *                                  with which to write the end of
     *                                  the list.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to end a container.
     */

    static inline WEAVE_ERROR EndList(ReferencedTLVData &aList, nl::Weave::TLV::TLVWriter &aWriter)
    {
        WEAVE_ERROR err = WEAVE_NO_ERROR;

        err = EndList(aWriter);

        aList.theLength = aWriter.GetLengthWritten();

        return err;
    };

    /**
     *  @brief
     *    Start writing a data list element.
     *
     *  Write the TLV for the beginning of a WDM data list element.
     *
     *  @param [in]     aWriter         A reference to a TLV writer
     *                                  with which to start writing.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to start a container.
     */

    static inline WEAVE_ERROR StartDataListElement(nl::Weave::TLV::TLVWriter &aWriter)
    {
        nl::Weave::TLV::TLVType itemContainer;

        return aWriter.StartContainer(nl::Weave::TLV::AnonymousTag, nl::Weave::TLV::kTLVType_Structure, itemContainer);
    };

    /**
     *  @brief
     *    Finish writing a data list element.
     *
     *  Write the TLV for the end of a WDM data list element. Note this
     *  this automatically passes in a type of kTLVType_Array to the
     *  EndContainer() call assuming that we are always closing a list
     *  item.
     *
     *  @param [in]     aWriter         A reference to a TLV writer
     *                                  with which to write the end of
     *                                  the item.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to end a container.
     */

    static inline WEAVE_ERROR EndDataListElement(nl::Weave::TLV::TLVWriter &aWriter)
    {
        /*
         * obviously, the outer container of a list element is a
         * "list", i.e. an array.
         */

        return aWriter.EndContainer(nl::Weave::TLV::kTLVType_Array);
    };

    bool CheckWDMTag(uint32_t aTagNum, nl::Weave::TLV::TLVReader &aReader);

    /**
     *  @brief
     *    Validate that a TLV element being read has the expected WDM
     *    tag.
     *
     *  @param [in]     aTagNum         The 32-bit tag number of the
     *                                  expected WDM tag.
     *
     *  @param [in]     aReader         A TLV reader positioned at the
     *                                  element to be validated.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise
     *  #WEAVE_ERROR_INVALID_TLV_TAG if the tag does not match the
     *  given tag number when interpreted as a WDM tag.
     */

    static inline WEAVE_ERROR ValidateWDMTag(uint32_t aTagNum, nl::Weave::TLV::TLVReader &aReader)
    {
        WEAVE_ERROR err;

        if (CheckWDMTag(aTagNum, aReader))
            err = WEAVE_NO_ERROR;

        else
            err = WEAVE_ERROR_INVALID_TLV_TAG;

        return err;
    };

    /**
     *  @brief
     *    Check that a TLV element being read has the expected TLV
     *    type.
     *
     *  Check a given TLV type against
     *  the element type at the head of a TLV reader.
     *
     *  @sa WeaveTLVTypes.h
     *
     *  @param [in]     aType           The TLVType to be checked
     *                                  against a specific element
     *
     *  @param [in]     aReader         A reference to a TLV reader
     *                                  positioned at the element to
     *                                  be checked
     *
     *  @return true iff the TLVType of the element and aType match.
     */

    static inline bool CheckTLVType(nl::Weave::TLV::TLVType aType, nl::Weave::TLV::TLVReader &aReader)
    {
        nl::Weave::TLV::TLVType type = aReader.GetType();

        return type == aType;
    };

    /**
     *  @brief
     *    Validate that a TLV element being read has the expected TLV
     *    type.
     *
     *  Check a given TLV type against
     *  the element type at the head of a TLV reader and return an
     *  error if there is no match.
     *
     *  @sa WeaveTLVTypes.h
     *
     *  @param [in]     aType           The TLVType to be validated
     *                                  against a specific element.
     *
     *  @param [in]     aReader         A reference to a TLV reader
     *                                  positioned at the element to
     *                                  be validated.
     *
     *  @return #WEAVE_NO_ERROR if there is a match or
     *  #WEAVE_ERROR_WRONG_TLV_TYPE if not.
     */

    inline WEAVE_ERROR ValidateTLVType(nl::Weave::TLV::TLVType aType, nl::Weave::TLV::TLVReader &aReader)
    {
        WEAVE_ERROR err;

        if (CheckTLVType(aType, aReader))
            err = WEAVE_NO_ERROR;

        else
            err = WEAVE_ERROR_WRONG_TLV_TYPE;

        return err;
    };

    WEAVE_ERROR OpenPathList(ReferencedTLVData &aPathList, nl::Weave::TLV::TLVReader &aReader);

    WEAVE_ERROR OpenDataList(ReferencedTLVData &aDataList, nl::Weave::TLV::TLVReader &aReader);

    WEAVE_ERROR OpenDataListElement(nl::Weave::TLV::TLVReader &aReader, nl::Weave::TLV::TLVReader &aPathReader, uint64_t &aVersion);

    /**
     *  @brief
     *    Stop reading a WDM path or data list.
     *
     *  This method assumes that the list in question is the topmost
     *  TLV element and so passes kTLVType_Sructure to ExitContainer().
     *
     *  @param [in,out] aReader         A TLV reader positioned in
     *                                  a WDM path or data list.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to exit a container.
     */

    inline WEAVE_ERROR CloseList(nl::Weave::TLV::TLVReader &aReader)
    {
        return aReader.ExitContainer(nl::Weave::TLV::kTLVType_Structure);
    };

    /**
     *  @brief
     *    Stop reading a WDM data list element.
     *
     *  This method assumes that the element in question is part of a
     *  WDM data list and so passes kTLVType_Array to ExitContainer().
     *
     *  @param [in,out] aReader         A TLV reader positioned in
     *                                  a WDM data list element.
     *
     *  @return #WEAVE_NO_ERROR On success. Otherwise return a
     *  #WEAVE_ERROR reflecting an inability to exit a container.
     */

    inline WEAVE_ERROR CloseDataListElement(nl::Weave::TLV::TLVReader &aReader)
    {
        return aReader.ExitContainer(nl::Weave::TLV::kTLVType_Array);
    };

    /*
     * it also turns out that we have to support a range of instance
     * identifiers.  we make the assumption that, at least in an
     * embedded context, they are all binary encodings. so, that means
     * that for all the numeric ones we can probably get away with
     * using a uint64 - since that will be the normal case anyway -
     * and for longer values we can use the TLV byte array.
     *
     * what this means, sadly, is that all the "convenience" methods
     * below that take or extract an instance ID have to account for
     * both types.
     */

    WEAVE_ERROR EncodePath(nl::Weave::TLV::TLVWriter &aWriter,
                           const uint64_t &aTag,
                           uint32_t aProfileId,
                           const uint64_t &aInstanceId,
                           uint16_t aPathLen,
                           ...);

    WEAVE_ERROR EncodePath(nl::Weave::TLV::TLVWriter &aWriter,
                           const uint64_t &aTag,
                           uint32_t aProfileId,
                           const uint32_t aInstanceIdLen,
                           const uint8_t *aInstanceId,
                           uint16_t aPathLen,
                           ...);

    WEAVE_ERROR EncodePath(nl::Weave::TLV::TLVWriter &aWriter,
                           const uint64_t &aTag,
                           uint32_t aProfileId,
                           const char *aInstanceId,
                           uint16_t aPathLen,
                           ...);

    /*
     * and for compatibility with Topaz, actually with older versions
     * of the Service that were in use under Topaz 1.0, we need these
     * versions.
     */

    WEAVE_ERROR EncodeDeprecatedPath(nl::Weave::TLV::TLVWriter &aWriter,
                                     const uint64_t &aTag,
                                     uint32_t aProfileId,
                                     const uint64_t &aInstanceId,
                                     uint16_t aPathLen,
                                     ...);

    WEAVE_ERROR EncodeDeprecatedPath(nl::Weave::TLV::TLVWriter &aWriter,
                                     const uint64_t &aTag,
                                     uint32_t aProfileId,
                                     const char *aInstanceId,
                                     uint16_t aPathLen,
                                     ...);

    /**
     *  @class ProfileDatabase
     *
     *  @brief
     *    The abstract ProfileDatabase auxiliary class.
     *
     *  WDM separates the protocol implementation from the data
     *  management implementation and, at least in principle, leaves
     *  most of the latter to the application developer. All of the
     *  interesting calls in WDM and all of the abstract methods that
     *  the profile developer is required to implement take TLV-encoded
     *  path lists or data lists. This puts a burden on profile
     *  developers and, in practice, will cause a lot of code
     *  duplication as developer after developer writes the same code
     *  for packing and unpacking TLV and so on. To ease things a bit
     *  we provide a kind of "data management toolkit".
     *
     *  This auxiliary class provides support for storing and retrieving data
     *  provided that the necessary concrete ProfileData sub-classes have been
     *  supplied and added to the LookupProfileData() method below.
     */

    class ProfileDatabase
    {
    public:

        /**
         *  @class ProfileData
         *
         *  @brief
         *    The abstract ProfileData auxiliary inner class.
         *
         *  ProfileDatabase sub-class implementers should implement
         *  sub-classes of this auxiliary inner class as well. The
         *  function of ProfileData objects is to provide hooks
         *  whereby concrete data may be stored, given a its
         *  representation as TLV and retrieved as a TLV
         *  representation given a TLV-encoded list of paths.
         */

        class ProfileData
        {
        public:
            ProfileData(void);

            virtual ~ProfileData(void);

            virtual WEAVE_ERROR Store(nl::Weave::TLV::TLVReader &aPathReader, uint64_t aVersion, nl::Weave::TLV::TLVReader &aDataReader);

            /**
             *  @brief
             *    Store a data item based on its tag.
             *
             *  @note
             *    ProfileDatabase subclass implementers must supply a
             *    concrete implementation of this method in order to
             *    store a particular kind of data under a known tag.
             *
             *  @param [in]     aTag            A reference to the
             *                                  fully-qualified 64-bit
             *                                  TLV tag under which
             *                                  the data should be
             *                                  stored.
             *
             *  @param [in]     aDataReader     A TLV reader
             *                                  positioned at the data
             *                                  item to be stored.
             *
             *  @return #WEAVE_NO_ERROR on success, otherwise return
             *  a #WEAVE_ERROR reflecting an inability either to
             *  recognize the tag or to store the data.
             */

            virtual WEAVE_ERROR StoreItem(const uint64_t &aTag, nl::Weave::TLV::TLVReader &aDataReader) = 0;

            /**
             *  @brief
             *    Write out a data item given a residual WDM path.
             *
             *  ProfileDatabase subclass implementers must provide a
             *  concrete implementation for this method in every case
             *  where the individual elements of a ProfileData subclass
             *  object are accessible under particular tags.
             *
             *  @param [in]     aPathReader     A reference to a TLV
             *                                  reader positioned in a
             *                                  WDM path after the
             *                                  profile information,
             *                                  i.e. at the 'residual'
             *                                  path elements if any.
             *
             *  @param [in]     aDataWriter     A reference to a TLV
             *                                  writer used to write
             *                                  out the data indicated
             *                                  by the residual path.
             *
             *  @return #WEAVE_NO_ERROR On success. Otherwise return a
             *  #WEAVE_ERROR reflecting an inability to recognize a
             *  residual tag or else to write the corresponding data.
             */

            virtual WEAVE_ERROR Retrieve(nl::Weave::TLV::TLVReader &aPathReader, nl::Weave::TLV::TLVWriter &aDataWriter) = 0;

            /*
             * data members:
             */

            /**
             *  @brief
             *    Profile data version.
             *
             *  The version given here in the ProfileData object
             *  applies to the whole profile data set for a particular
             *  instance.
             */

            uint64_t mVersion;

        };

        WEAVE_ERROR Store(ReferencedTLVData &aDataList);

        WEAVE_ERROR Retrieve(ReferencedTLVData &aPathList, ReferencedTLVData &aDataList);

        WEAVE_ERROR Retrieve(ReferencedTLVData &aPathList, nl::Weave::TLV::TLVWriter &aWriter);

        WEAVE_ERROR LookupProfileData(nl::Weave::TLV::TLVReader &aPathReader, ProfileData **aProfileData);

        WEAVE_ERROR LookupDataFromProfileDescriptor(nl::Weave::TLV::TLVReader &aDescReader, ProfileData **aProfileData);

        /**
         *  @brief
         *    Look up a ProfileData object.
         *
         *  Look up a specific ProfileData object given a profile ID
         *  and an (optional) instance ID< provided as a TLV reader.
         *
         *  @param [in]     aProfileId      The 32-bit profile number
         *                                  of the profile of interest.
         *
         *  @param [in]     aInstanceIdRdr  A pointer to a TLV reader
         *                                  positioned at the instance
         *                                  identifier data. If not
         *                                  instance identifier was
         *                                  provided then this shall
         *                                  be NULL.
         *
         *  @param [out]    aResult         A pointer, intended to return a
         *                                  pointer to the ProfileData object
         *                                  of interest.
         *
         *  @return #WEAVE_NO_ERROR On success. Otherwise return a
         *  #WEAVE_ERROR reflecting an inability to find a ProfileData
         *  object.
         */

        virtual WEAVE_ERROR LookupProfileData(uint32_t aProfileId, nl::Weave::TLV::TLVReader *aInstanceIdRdr, ProfileData **aResult) = 0;

    protected:

        WEAVE_ERROR StoreInternal(nl::Weave::TLV::TLVReader &aPathReader, uint64_t aVersion, nl::Weave::TLV::TLVReader &aDataReader);
    };

}; // WeaveMakeManagedNamespaceIdentifier(DataManagement, kWeaveManagedNamespaceDesignation_Legacy)
}; // Profiles
}; // Weave
}; // nl

#endif // _WEAVE_DATA_MANAGEMENT_PROFILE_DATABASE_LEGACY_H