Action.hpp

/*
 * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. 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.
 * A copy of the License is located at
 *
 *  http://aws.amazon.com/apache2.0
 *
 * or in the "license" file accompanying this file. This file 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 Action.hpp
 * @brief Action Base class and related definitions for IoT Client
 *
 * Defines a base class to be used by all Actions that can be run by the
 * IoT Client. Also contains definitions for related Action types like
 * ActionType, ActionState and ActionData
 */

#pragma once

#include <string>
#include <iostream>
#include <memory>
#include <atomic>

#include "util/Utf8String.hpp"
#include "util/threading/ThreadTask.hpp"

#include "ResponseCode.hpp"
#include "NetworkConnection.hpp"

#define DEFAULT_NETWORK_ACTION_THREAD_SLEEP_DURATION_MS 100

namespace awsiotsdk {
    /**
     * @brief ActionType Enum Class
     *
     * Defines a strongly typed enum which specifies different Action Types.
     * Actions can be registered in the core client for each of these Types.
     */
    enum class ActionType {
        RESERVED_ACTION = 0,
        CORE_PROCESS_INBOUND = 1,
        CORE_PROCESS_OUTBOUND = 2,
        CONNECT = 3,
        DISCONNECT = 4,
        PUBLISH = 5,
        PUBACK = 6,
        PUBREC = 7,
        PUBREL = 8,
        PUBCOMP = 9,
        SUBSCRIBE = 10,
        READ_INCOMING = 11,
        KEEP_ALIVE = 12,
        PUBLISH_INBOUND = 13,
        UNSUBSCRIBE = 14,
        RECONNECT = 15,
        GREENGRASS_DISCOVER = 16
    };

    /**
     * @brief Action State Class
     *
     * Defines an Action State class which is retained by each Action for its lifetime
     * This is a pure virtual class, cannot be instantiated
     */
    class ActionState {
    public:
        /**
         * @brief Get Action ID of the next Action
         *
         * @return uint16_t Next Action ID
         */
        virtual uint16_t GetNextActionId() = 0;

        // Rule of 5 stuff
        // Keeping defaults, explicitly mentioned to avoid conflicts with future C++ specifications
        // Must always be able to copy and move
        ActionState() = default;                                 // Default constructor
        ActionState(const ActionState &) = delete;               // Copy constructor
        ActionState(ActionState &&) = delete;                    // Move constructor
        ActionState &operator=(const ActionState &) & = delete;  // Copy assignment operator
        ActionState &operator=(ActionState &&) & = delete;       // Move assignment operator
        virtual ~ActionState() = default;                        // Default destructor
    };

    /**
     * @brief Action Data Class
     *
     * Defines an Action Data class which contains dynamic information to be used by the action
     * Instance of concrete implementation of this class is passed as argument each time Perform Action is called
     * This is a pure virtual class, cannot be instantiated
     */
    class ActionData {
    public:
        /**
         * Define a type for the Async Ack notification handler
         * Clients can provide an instance of this to receive notification on status of Async API calls
         */
        typedef std::function<void(uint16_t action_id, ResponseCode rc)> AsyncAckNotificationHandlerPtr;

        // Rule of 5 stuff
        // Since virtual destructor is present, derived classes will have to explicitly define defaults
        // Must always be able to copy and move
        ActionData() = default;                                 // Default constructor
        ActionData(const ActionData &) = default;               // Copy constructor
        ActionData(ActionData &&) = default;                    // Move constructor
        ActionData &operator=(const ActionData &) & = default;  // Copy assignment operator
        ActionData &operator=(ActionData &&) & = default;       // Move assignment operator
        virtual ~ActionData() = default;                        // Default destructor

        AsyncAckNotificationHandlerPtr p_async_ack_handler_;    ///< Handler to call when response is received for this action

        /**
         * @brief Get ID of the current run of this Action
         * @return uint16_t - Action ID
         */
        virtual uint16_t GetActionId() = 0;

        /**
         * @brief Set the Action ID for this run of the Action
         *
         * @param action_id - new Action ID
         */
        virtual void SetActionId(uint16_t action_id) = 0;
    };

    /**
     * @brief Action Class
     *
     * Defines a base class for SDK Actions. Provides basic template for concrete implementations.
     * Also includes code for Thread sync with client core.
     * All Actions that can be performed by the Client Core must inherit from this class.
     * This is a pure virtual class and cannot be instantiated
     *
     */
    class Action {
    public:
        /**
         * Define a type for Create Factory method. Takes Action state as argument and returns a unique_ptr to a new
         * action instance
         */
        typedef std::function<std::unique_ptr<Action>(std::shared_ptr<ActionState> p_action_state)> CreateHandlerPtr;

        /**
         * @brief Get Type of this Action
         * @return ActionType
         */
        ActionType GetActionType() {
            return action_type_;
        }

        /**
         * @brief Get information/description about the current action
         *
         * Gets runtime information about the currently running Action if it was set when the action was created
         *
         * @return String containing Info Text
         */
        util::String GetActionInfo() {
            return action_info_string_;
        }

        /**
         * @brief Sets the parent thread sync variable
         *
         * @param p_thread_continue - Pointer to the new sync variable to use
         */
        void SetParentThreadSync(std::shared_ptr<std::atomic_bool> p_thread_continue) {
            p_thread_continue_ = p_thread_continue;
        }

        /**
         * @brief Virtual base function for Performing Action
         *
         * This function is called by Client Core and defines how the Action is Performed.
         * This is a pure virtual function. Inherited classes MUST implement this.
         *
         * @param p_network_connection - Network connection to be used to perform the Action
         * @param p_action_data - Action data to be used for this run of the action
         * @return ResponseCode indicating result of the API call
         */
        virtual ResponseCode PerformAction(std::shared_ptr<NetworkConnection> p_network_connection,
                                           std::shared_ptr<ActionData> p_action_data) = 0;

        // Rule of 5 stuff
        // Disabling default, move and copy constructors
        // Actions instances can be run as threads if needed and should not be copied or moved
        Action() = delete;                             // Delete Default constructor
        Action(const Action &) = delete;               // Copy constructor
        Action(Action &&) = delete;                    // Move constructor
        Action &operator=(const Action &) & = delete;  // Copy assignment operator
        Action &operator=(Action &&) & = delete;       // Move assignment operator
        virtual ~Action() = default;                   // Default destructor

        /**
         * @brief Action Constructor
         *
         * @param action_type - Type fo the Action being instantiated
         * @param action_info_string - Info string describing the action
         */
        Action(ActionType action_type, util::String action_info_string);

    protected:
        ActionType action_type_;                               ///< Type of the action
        util::String action_info_string_;                      ///< Info string
        std::shared_ptr<std::atomic_bool> p_thread_continue_;  ///< Shared atomic variable used for sync when action is run in separate thread

        /**
         * @brief Generic Network Read function for all actions
         * @param p_network_connection - Network connection to be used to perform Read
         * @param read_buf - Buffer read data should be copied to. Assumed to already have enough memory reserved
         * @param bytes_to_read - Number of bytes to read
         * @return ResponeCode indicating result of the API call
         */
        ResponseCode ReadFromNetworkBuffer(std::shared_ptr<NetworkConnection> p_network_connection,
                                           util::Vector<unsigned char> &read_buf, size_t bytes_to_read);

        /**
         * @brief Generic Network Write function for all actions
         * @param p_network_connection - Network connection to be used to perform Write
         * @param read_buf - Buffer containing data to be written to the network instance
         * @return ResponeCode indicating result of the API call
         */
        ResponseCode WriteToNetworkBuffer(std::shared_ptr<NetworkConnection> p_network_connection,
                                          const util::String &write_buf);
    };
}