text: /*
   *
   *    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.
   */
  #ifndef NETWORKINFO_H
  #define NETWORKINFO_H
  
  #include <Weave/Core/WeaveCore.h>
  #include <Weave/Support/CodeUtils.h>
  #include <Weave/Core/WeaveEncoding.h>
  #include <Weave/Profiles/WeaveProfiles.h>
  #include "NetworkProvisioning.h"
  #include <Weave/Profiles/common/CommonProfile.h>
  
  /**
   * @file
   *    This file defines a utility class for serializing and
   *    deserializing NetworkProvisioning payloads.
   */
  namespace nl {
  namespace Weave {
  namespace Profiles {
  namespace NetworkProvisioning {
  
  
  /**
   * A utility class for serializing and deserializing payloads
   * communicated via NetworkProvisioning profile: it encapsulates
   * information pertinent to the detecting and configuring networks.
   * The class relies on intermediate storage of network provisioning
   * information (intermediate between the ultimate store of the
   * information and the network payload) and uses dynamic memory
   * management to give the resulting object flexible runtime.  As such,
   * this class is not suitable for the most constrained environments,
   * but may be used on larger systems.
   */
  class NL_DLL_EXPORT NetworkInfo
  {
  public:
      NetworkInfo();
      ~NetworkInfo();
  
      ::nl::Weave::Profiles::NetworkProvisioning::NetworkType
            NetworkType;              /**< The type of network. */
      int64_t NetworkId;              /**< The network id assigned to the network by the device, -1 if not specified. */
  
      // ---- WiFi-specific Fields ----
      char *WiFiSSID;                 /**< The WiFi SSID, or NULL if not specified. It is a NUL-terminated,
                                       * dynamically-allocated C-string, owned by the class.  Destroyed on any condition
                                       * that calls `Clear()` on the object. */
      ::nl::Weave::Profiles::NetworkProvisioning::WiFiMode
            WiFiMode;                 /**< The operating mode of the WiFi network.*/
      ::nl::Weave::Profiles::NetworkProvisioning::WiFiRole
            WiFiRole;                 /**< The role played by the device on the WiFi network. */
      ::nl::Weave::Profiles::NetworkProvisioning::WiFiSecurityType
            WiFiSecurityType;         /**< The WiFi security type. */
      uint8_t *WiFiKey;               /**< The WiFi key, or NULL if not specified. It is a dynamically allocated array
                                       * of arbitrary octets, owned by the class, with length specified by `WiFiKeyLen`.
                                       * Destroyed on any condition that calls `Clear()` on the object. */
      uint32_t WiFiKeyLen;            /**< The length in bytes of the WiFi key. */
  
      // ---- Thread-specific Fields ----
      char *ThreadNetworkName;        /**< The name of the Thread network, or NULL if not specified. It is a
                                       * NUL-terminated, dynamically-allocated C-string, owned by the class.  Destroyed
                                       * on any condition that calls `Clear()` on the object. */
      uint8_t *ThreadExtendedPANId;   /**< The Thread extended PAN id (8 bytes). */
      uint8_t *ThreadNetworkKey;      /**< The Thread master network key , or NULL if not specified. It is a dynamically
                                       * allocated array of arbitrary octets, owned by the class, with length specified
                                       * by `ThreadNetworkKeyLen`.  Destroyed on any condition that calls `Clear()` on
                                       * the object. */
      uint32_t ThreadNetworkKeyLen;   /**< The length in bytes of the Thread master network key. */
  
      // ---- General Fields ----
      int16_t WirelessSignalStrength; /**< The signal strength of the network, or INT16_MIN if not
                                       * available/applicable. */
      bool Hidden;                    /**< Whether or not the network is hidden. */
  
  
      /**
       * Replace the contents of this NetworkInfo object with the deep copy of the contents of the argument.
       *
       * @param[in] dest               NetworkInfo object containing information to be copied into this object.
       *
       * @retval #WEAVE_NO_ERROR        On success.
       *
       * @retval #WEAVE_ERROR_NOT_IMPLEMENTED When the platform does not support malloc or free.
       *
       * @retval #WEAVE_ERROR_NO_MEMORY On memory allocation failures.
       */
      WEAVE_ERROR CopyTo(NetworkInfo& dest);
  
      /**
       * Merge the contents of this NetworkInfo object with the deep copy of the contents of the argument. All the
       * non-default values from the argument object replace the values in this object.
       *
       * @param[in] dest               NetworkInfo object containing information to be copied into this object.
       *
       * @retval #WEAVE_NO_ERROR        On success.
       *
       * @retval #WEAVE_ERROR_NOT_IMPLEMENTED When the platform does not support malloc or free.
       *
       * @retval #WEAVE_ERROR_NO_MEMORY On memory allocation failures.
       */
      WEAVE_ERROR MergeTo(NetworkInfo& dest);
  
      /**
       * Reset to default and free all values within this NetworkInfo object
       */
      void Clear(void);
  
      enum
      {
          kEncodeFlag_EncodeCredentials   = ::nl::Weave::Profiles::NetworkProvisioning::kGetNetwork_IncludeCredentials,
          kEncodeFlag_All                 = 0xFF
      };
  
      /**
       * Deserialize the content of this NetworkInfo object from its TLV representation
       *
       * @param[in] reader   TLVReader positioned to the structure element containing network info.
       *
       * @returns #WEAVE_NO_ERROR On success, WEAVE_ERROR_INVALID_TLV_ELEMENT on any element not conforming to the
       *                     network provisioning profile, any of the TLV reader errors on incorrect decoding of
       *                     elements.
       */
      WEAVE_ERROR Decode(nl::Weave::TLV::TLVReader& reader);
  
      /**
       * Serialize the content of this NetworkInfo object into its TLV representation
       *
       * @param[in] writer TLVWriter positioned at the place where the object will be serialized to.  The function emits
       *                   an anonymous tag for this object when this object is a part of array of elements or a profile
       *                   tag for kTag_NetworkInformation when emitted as a standalone element.
       *
       * @param[in] flags  Flags controlling whether the credentials of the NetworkInfo should be serialized.
       *
       * @returns #WEAVE_NO_ERROR On success, WEAVE_ERROR_INVALID_TLV_ELEMENT on any element not conforming to the
       *                   network provisioning profile, any of the TLV reader errors on incorrect decoding of elements.
       */
      WEAVE_ERROR Encode(nl::Weave::TLV::TLVWriter& writer, uint8_t encodeFlags) const;
  
      /**
       * Deserialize a list of NetworkInfo elements from its TLV representation.
       *
       * @param[in] reader TLVReader positioned at the array start. On successful return, the writer is positioned after
       *                         the end of the array.
       *
       * @param[inout] elemCount On input, maximum number of elements to deserialize from the TLVReader.  On output, the
       *                         number of elements actually deserialized from the stream.
       *
       * @param[inout] elemArray A reference to the array of NetworkInfo elements that will contain the deserialized
       *                         NetworkInfo objects.  When the array is NULL, it is allocated internally by the
       *                         function below, otherwise it is assumed that the externally allocated array contains at
       *                         least elemCount objects.
       *
       * @retval #WEAVE_NO_ERROR  On success.
       *
       * @retval #WEAVE_ERROR_NOT_IMPLEMENTED on platforms that do not support dynamic memory management.
       *
       * @retval other Errors returned from the `Decode()` function.
       */
      static WEAVE_ERROR DecodeList(nl::Weave::TLV::TLVReader& reader, uint16_t& elemCount, NetworkInfo *& elemArray);
  
      /**
       * Serialize an array of NetworkInfo objects into its TLV representation. The array will be an anonymous element
       * in the TLV representation.
       *
       * @param[in] writer      Appropriately positioned TLVWriter
       *
       * @param[in] arrayLen    Number of elements in the `elemArray`.
       *
       * @param[in] elemArray   The array of NetworkInfo objects to be serialized.
       *
       * @param[in] encodeFlags Flags controlling whether the credentials of the NetworkInfo should be serialized.
       *
       * @param[out] encodedElementCount The number of elements actually serialized.
       *
       * @retval #WEAVE_NO_ERROR  On success.
       *
       * @retval Other           Errors returned from the `Encode()` function.
       *
       */
      static WEAVE_ERROR EncodeList(nl::Weave::TLV::TLVWriter& writer, uint16_t elemCount, const NetworkInfo *elemArray,
          uint8_t encodeFlags);
      /**
       * Serialize an array of NetworkInfo objects into its TLV representation selecting only networks of a specific type.
       *
       * @param[in] writer      Appropriately positioned TLVWriter
       *
       * @param[in] arrayLen    Number of elements in the `elemArray`.
       *
       * @param[in] elemArray   The array of NetworkInfo objects to be serialized.
       *
       * @param[in] networkType The type of NetworkInfo objects to serialize
       *
       * @param[in] encodeFlags Flags controlling whether the credentials of the NetworkInfo should be serialized.
       *
       * @param[out] encodedElementCount The number of elements actually serialized.
       *
       * @retval #WEAVE_NO_ERROR  On success.
       *
       * @retval Other           Errors returned from the `Encode()` function.
       *
       */
      static WEAVE_ERROR EncodeList(nl::Weave::TLV::TLVWriter& writer, uint16_t arrayLen, const NetworkInfo *elemArray,
          ::nl::Weave::Profiles::NetworkProvisioning::NetworkType networkType, uint8_t encodeFlags, uint16_t& encodedElemCount);
  };
  
  } // namespace NetworkProvisioning
  } // namespace Profiles
  } // namespace Weave
  } // namespace nl
  #endif //NETWORKINFO_H
  