/*********************************************************************
 *
 * Software License Agreement (BSD License)
 *
 * Cổng ra phía navigation của mission layer.
 *
 * Author: DuongTD
 *********************************************************************/
#ifndef MISSION_ADAPTERS_NAVIGATION_CLIENT_H_
#define MISSION_ADAPTERS_NAVIGATION_CLIENT_H_

#include <memory>

#include <mission_adapters/types.h>

namespace mission_adapters
{
    /**
     * @class NavigationClient
     * @brief Đường duy nhất để mission layer điều khiển navigation.
     *
     * Gói này KHÔNG biết navigation runtime nào đang chạy phía sau: bridge phía runtime hiện thực
     * interface này, test hiện thực bằng fake. Nhờ vậy chiều phụ thuộc luôn một chiều và mission
     * layer test được mà không cần robot.
     *
     * Bất biến an toàn: mọi đường thoát của một mission — bị thay thế, bị huỷ, emergency — đều phải
     * đi qua @ref cancelActive. Mission layer quên mission mà không bảo navigation dừng thì robot
     * vẫn chạy tiếp tới goal cũ.
     */
    class NavigationClient
    {
    public:
        virtual ~NavigationClient() = default;

        /**
         * @brief Giao một mission cho navigation chạy.
         * @param mission Mission bất biến, luôn khác null.
         * @return false nếu navigation từ chối (goal không hợp lệ, chưa initialize...). Khi đó
         *         mission layer ghi nhận chặng này thất bại thay vì chờ vô hạn.
         */
        virtual bool dispatch(const std::shared_ptr<const Mission>& mission) = 0;

        /**
         * @brief Yêu cầu dừng mission đang chạy.
         * @param id Mission cần dừng — navigation bỏ qua nếu nó đã chạy sang mission khác.
         *
         * Kết quả cuối cùng vẫn quay về qua đường outcome bình thường (navDoneEvent /
         * navFailedEvent mang cùng @p id), không phải qua giá trị trả về của hàm này.
         */
        virtual void cancelActive(MissionId id) = 0;
    };

} // namespace mission_adapters

#endif  // MISSION_ADAPTERS_NAVIGATION_CLIENT_H_
