feat: add structures for MTR arrival and station information handling

main/external/mtr/mtr.h

@@ -0,0 +1,56 @@
+#include "assets/mtr_line_station_json.h"
+#include "cJSON.h"
+#include <string>
+#include "esp_log.h"
+#include "external/mtr/line_info.h"
+#include <vector>
+#include "network/network.h"
+
+// Forward declaration
+struct StationArrivalInfo;
+struct LineInfo;
+
+enum class MtrArrivalErrorCode {
+  NONE = 0,
+  LINE_NOT_FOUND = 1,
+  STATION_NOT_FOUND = 2,
+  NO_ARRIVAL_INFO = 3,
+  UNKNOWN = 99,
+};
+
+enum class Language {
+  EN,
+  TC,
+};
+
+class MTRNextTrainHandler {
+public:
+
+  /**
+   * @brief Construct a new MTR Next Train Handler object
+   * @param json Pointer to cJSON object containing MTR Next Train data
+   *
+   * > Caller transfers ownership of the cJSON object to MTRNextTrainHandler
+   *
+   * cJSON structure for MTR Next Train data
+   * This structure is used to parse and store the MTR Next Train JSON data.
+   * Record<code name string, {name: string, code: string, color: hex string, station: {code: string, name: string}[]}>
+   */
+  MTRNextTrainHandler();
+  ~MTRNextTrainHandler();
+
+  std::vector<LineInfo> get_lines();
+
+  MtrArrivalErrorCode get_next_arrival_info(
+    NetworkHandler* network_handler,
+    std::string& line_code,
+    std::string& station_code,
+    Language lang = Language::TC,
+    StationArrivalInfo*& out_info
+  );
+
+private:
+  cJSON* mtr_data;
+};
+
+