weave/src/lib/profiles/network-provisioning/NetworkInfo.h

/*
 *
 *    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