/*
 *
 *    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 the Weave Network Provisioning Profile, used
 *      to configure network interfaces.
 *
 *      The Network Provisioning Profile facilitates client-server
 *      operations such that the client (the controlling device) can
 *      trigger specific network functionality on the server (the device
 *      undergoing network provisioning).  These operations revolve around
 *      the steps necessary to provision the server device's network
 *      interfaces (such as 802.15.4/Thread and 802.11/Wi-Fi) provisioned
 *      such that the device may participate in those networks.  This includes
 *      scanning and specifying network names and security credentials.
 *
 */

#ifndef NETWORKPROVISIONING_H_
#define NETWORKPROVISIONING_H_

#include <Weave/Support/NLDLLUtil.h>
#include <Weave/Core/WeaveCore.h>
#include <Weave/Core/WeaveServerBase.h>
#include <Weave/Core/WeaveEncoding.h>
#include <Weave/Core/WeaveTLV.h>

/**
 *   @namespace nl::Weave::Profiles::NetworkProvisioning
 *
 *   @brief
 *     This namespace includes all interfaces within Weave for the
 *     Weave Network Provisioning profile, the first of the three
 *     Weave provisioning profiles.
 *
 *     The interfaces define status codes, message types, data element
 *     tags, other constants, a server object, and a delegate object.
 *
 *     The Nest Weave Network Provisioning Profile is focused on
 *     providing the data to get the network interfaces, such as
 *     802.15.4/Thread and 802.11/Wi-Fi, for a Weave device
 *     provisioned such that the device may participate in those
 *     networks.
 */

namespace nl {
namespace Weave {
namespace Profiles {
namespace NetworkProvisioning {

using nl::Weave::TLV::TLVReader;
using nl::Weave::TLV::TLVWriter;

/**
 *  Network Provisioning Status Codes.
 */
enum
{
    kStatusCode_UnknownNetwork                  = 1,            /**< A provisioned network with the specified network ID was not found. */
    kStatusCode_TooManyNetworks                 = 2,            /**< The maximum number of provisioned networks has been reached. */
    kStatusCode_InvalidNetworkConfiguration     = 3,            /**< The specified network configuration is invalid. */
    kStatusCode_UnsupportedNetworkType          = 4,            /**< The specified network type is unknown or unsupported. */
    kStatusCode_UnsupportedWiFiMode             = 5,            /**< The specified WiFi mode is unsupported. */
    kStatusCode_UnsupportedWiFiRole             = 6,            /**< The specified WiFi role is unsupported. */
    kStatusCode_UnsupportedWiFiSecurityType     = 7,            /**< The specified WiFi security type is unsupported. */
    kStatusCode_InvalidState                    = 8,            /**< The network provisioning operation could not be performed in the current state. */
    kStatusCode_TestNetworkFailed               = 9,            /**< The connectivity test of the specified network failed. */
                                                                // XXX Placeholder for more detailed errors to come
    kStatusCode_NetworkConnectFailed            = 10            /**< An attempt to connect to the specified network failed. */
};

/**
 * Network Provisioning Message Types.
 */
enum
{
    kMsgType_ScanNetworks                       = 1,
    kMsgType_NetworkScanComplete                = 2,
    kMsgType_AddNetwork                         = 3,
    kMsgType_AddNetworkComplete                 = 4,
    kMsgType_UpdateNetwork                      = 5,
    kMsgType_RemoveNetwork                      = 6,
    kMsgType_EnableNetwork                      = 7,
    kMsgType_DisableNetwork                     = 8,
    kMsgType_TestConnectivity                   = 9,
    kMsgType_SetRendezvousMode                  = 10,
    kMsgType_GetNetworks                        = 11,
    kMsgType_GetNetworksComplete                = 12,
    kMsgType_GetLastResult                      = 13
};

/**
 * @anchor NetworkProvisioningDataElementTags
 * Network Provisioning Data Element Tags.
 */
enum
{
    /**
     * Top-level Data Elements (profile-specific).
     */
    kTag_Networks                               = 1,	/**< An array of NetworkConfiguration structures. [ array ] */
    kTag_EnabledNetworks                        = 2,	/**< An array of NetworkIds identifying the networks currently enabled on the device. [ array ] */
    kTag_RendezvousMode                         = 3,	/**< A bit field indicating the currently active rendezvous mode. [ uint ] */

    /**
     * General-Purpose Data Elements (profile-specific).
     */
    kTag_NetworkInformation                     = 32,	/**< A structure containing information for a network. [ struct ] */
    kTag_NetworkId                              = 33,	/**< An integer uniquely identifying a provisioned network. [ uint, 32-bit max ] */
    kTag_NetworkType                            = 34,	/**< An unsigned integer value identifying the type of a network. [ uint, 8-bit max ] */
    kTag_WirelessSignalStrength                 = 35,   /**< An signed integer value giving the signal strength of a wireless network in dBm. [ int, 16-bit max ] */

    /**
     * WiFi Data Elements (Profile-specific).
     */
    kTag_WiFiSSID                               = 64,	/**< A string containing a WiFi SSID. [ UTF-8 string ] */
    kTag_WiFiMode                               = 65,	/**< An integer identify the mode of operation of the WiFi network. [ uint, 8-bit max ] */
    kTag_WiFiRole                               = 66,	/**< An integer identify the role the device plays in the WiFi network. [ uint, 8-bit max ] */
    kTag_WiFiSecurityType                       = 67,	/**< An integer value identifying the type of security used by a WiFi network. [ uint, 8-bit max ] */
    kTag_WiFiPreSharedKey                       = 68,	/**< A byte string containing the WiFi password/pre-shared key. */

    /**
     * Thread Data Elements (profile-specific).
     */
    kTag_ThreadExtendedPANId                    = 80,   /**< The Thread extended PAN ID. [ byte string ] */
    kTag_ThreadNetworkName                      = 81,   /**< A UTF-8 string containing the name of the Thread network. [ UTF-8 string ] */
    kTag_ThreadNetworkKey                       = 82,   /**< The Thread master network key. [ bytes string ] */
    kTag_ThreadMeshPrefix                       = 83    /**< Thread mesh IPv6 /64 prefix (optional). [ bytes string, exactly 8 bytes ] */
};

/**
 * Network Types.
 */
enum NetworkType
{
    kNetworkType_NotSpecified                   = -1,

    kNetworkType_WiFi                           = 1,
    kNetworkType_Thread                         = 2
};

/**
 * WiFi Security Modes.
 */
enum WiFiSecurityType
{
    kWiFiSecurityType_NotSpecified              = -1,

    kWiFiSecurityType_None                      = 1,
    kWiFiSecurityType_WEP                       = 2,
    kWiFiSecurityType_WPAPersonal               = 3,
    kWiFiSecurityType_WPA2Personal              = 4,
    kWiFiSecurityType_WPA2MixedPersonal         = 5,
    kWiFiSecurityType_WPAEnterprise             = 6,
    kWiFiSecurityType_WPA2Enterprise            = 7,
    kWiFiSecurityType_WPA2MixedEnterprise       = 8
};

/**
 * WiFi Operating Modes.
 */
enum WiFiMode
{
    kWiFiMode_NotSpecified                      = -1,

    kWiFiMode_AdHoc                             = 1,
    kWiFiMode_Managed                           = 2
};

/**
 * Device WiFi Role.
 */
enum WiFiRole
{
    kWiFiRole_NotSpecified                      = -1,

    kWiFiRole_Station                           = 1,
    kWiFiRole_AccessPoint                       = 2
};

/**
 * Rendezvous Mode Flags.
 */
enum RendezvousModeFlags
{
    kRendezvousMode_EnableWiFiRendezvousNetwork = 0x0001,
    kRendezvousMode_EnableThreadRendezvous      = 0x0002
};

/**
 * Get Network Flags.
 */
enum GetNetworkFlags
{
    kGetNetwork_IncludeCredentials              = 0x01
};

/**
 * Delegate class for implementing Network Provisioning operations.
 */
class NetworkProvisioningDelegate : public WeaveServerDelegateBase
{
public:
    /**
     * Perform a network scan.
     *
     * @param[in] networkType   The technology (for example, WiFi or Thread) to scan.  @sa #NetworkType for valid types.
     *
     * @retval #WEAVE_NO_ERROR   On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from performing a network scan.
     */
    virtual WEAVE_ERROR HandleScanNetworks(uint8_t networkType) = 0;

    /**
     * Add a particular network.
     *
     * @param[in] networkInfoTLV    The network configuration encoded in TLV.  @sa @ref NetworkProvisioningDataElementTags for valid types.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from adding the network.
     */
    virtual WEAVE_ERROR HandleAddNetwork(PacketBuffer *networkInfoTLV) = 0;

    /**
     * Update a network's configuration.
     *
     * @param[in] networkInfoTLV    The network configuration encoded in TLV.  @sa @ref NetworkProvisioningDataElementTags for valid types.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from updating the network.
     */
    virtual WEAVE_ERROR HandleUpdateNetwork(PacketBuffer *networkInfoTLV) = 0;

    /**
     * Remove a configured network.
     *
     * @param[in] networkId     The ID of the network to remove.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from removing the network.
     */
    virtual WEAVE_ERROR HandleRemoveNetwork(uint32_t networkId) = 0;

    /**
     * Get the configured networks.
     *
     * @param[in] flags     Flags to filter the retrieved networks.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from getting the configured networks.
     */
    virtual WEAVE_ERROR HandleGetNetworks(uint8_t flags) = 0;

    /**
     * Enable the specified network.
     *
     * @param[in] networkId     The ID of the network to enable.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from enabling the network.
     */
    virtual WEAVE_ERROR HandleEnableNetwork(uint32_t networkId) = 0;

    /**
     * Disable the specified network.
     *
     * @param[in] networkId     The ID of the network to disable.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from disabling the network.
     */
    virtual WEAVE_ERROR HandleDisableNetwork(uint32_t networkId) = 0;

    /**
     * Test the connectivity of the specified network.
     *
     * @param[in] networkId     The ID of the network to test the connectivity of.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from testing connectivity.
     */
    virtual WEAVE_ERROR HandleTestConnectivity(uint32_t networkId) = 0;

    /**
     * Set the rendezvous mode.
     *
     * @param[in] rendezvousMode    The rendezvous mode to use.  @sa #RendezvousModeFlags for valid modes.
     *
     * @retval #WEAVE_NO_ERROR  On success.
     * @retval other            Other Weave or platform-specific error codes indicating that an error
     *                          occurred preventing the device from setting the rendezvous mode.
     */
    virtual WEAVE_ERROR HandleSetRendezvousMode(uint16_t rendezvousMode) = 0;

    /**
     * Enforce message-level access control for an incoming Network Provisioning request message.
     *
     * @param[in] ec            The ExchangeContext over which the message was received.
     * @param[in] msgProfileId  The profile id of the received message.
     * @param[in] msgType       The message type of the received message.
     * @param[in] msgInfo       A WeaveMessageInfo structure containing information about the received message.
     * @param[inout] result     An enumerated value describing the result of access control policy evaluation for
     *                          the received message. Upon entry to the method, the value represents the tentative
     *                          result at the current point in the evaluation process.  Upon return, the result
     *                          is expected to represent the final assessment of access control policy for the
     *                          message.
     */
    virtual void EnforceAccessControl(ExchangeContext *ec, uint32_t msgProfileId, uint8_t msgType,
                const WeaveMessageInfo *msgInfo, AccessControlResult& result);

    /**
     * Called to determine if the device is currently paired to an account.
     */
    // TODO: make this pure virtual when product code provides appropriate implementations.
    virtual bool IsPairedToAccount() const;
};

/**
 * Server class for implementing the Network Provisioning profile.
 */
// TODO: Additional documentation detail required (i.e. expected class usage, number in the system, instantiation requirements, lifetime).
class NL_DLL_EXPORT NetworkProvisioningServer : public WeaveServerBase
{
public:
    NetworkProvisioningServer(void);

    WEAVE_ERROR Init(WeaveExchangeManager *exchangeMgr);
    WEAVE_ERROR Shutdown(void);

    void SetDelegate(NetworkProvisioningDelegate *delegate);

    virtual WEAVE_ERROR SendNetworkScanComplete(uint8_t resultCount, PacketBuffer *scanResultsTLV);
    virtual WEAVE_ERROR SendAddNetworkComplete(uint32_t networkId);
    virtual WEAVE_ERROR SendGetNetworksComplete(uint8_t resultCount, PacketBuffer *resultsTLV);
    virtual WEAVE_ERROR SendSuccessResponse(void);
    virtual WEAVE_ERROR SendStatusReport(uint32_t statusProfileId, uint16_t statusCode, WEAVE_ERROR sysError = WEAVE_NO_ERROR);

protected:
    ExchangeContext *mCurOp;
    NetworkProvisioningDelegate *mDelegate;
    struct
    {
        uint32_t StatusProfileId;
        uint16_t StatusCode;
        WEAVE_ERROR SysError;
    } mLastOpResult;
    uint8_t mCurOpType;

private:
    static void HandleRequest(ExchangeContext *ec, const IPPacketInfo *pktInfo, const WeaveMessageInfo *msgInfo, uint32_t profileId,
            uint8_t msgType, PacketBuffer *payload);
    WEAVE_ERROR SendCompleteWithNetworkList(uint8_t msgType, int8_t resultCount, PacketBuffer *resultTLV);

    NetworkProvisioningServer(const NetworkProvisioningServer&);   // not defined
};

} // namespace NetworkProvisioning
} // namespace Profiles
} // namespace Weave
} // namespace nl

#endif /* NETWORKPROVISIONING_H_ */