feat: add structures for MTR arrival and station information handling

main/external/mtr/arrival.h

@@ -0,0 +1,55 @@
+#pragma once
+#include "external/mtr/arrival.h"
+#include "cJSON.h"
+#include "external/mtr/mtr.h"
+#include <string>
+#include <vector>
+
+// Forward declaration
+class MTRNextTrainHandler;
+
+struct ArrivalInfo {
+public:
+  // Caller transfers ownership of arrival_time to ArrivalInfo
+  ArrivalInfo(
+    const std::string& arrival_time,
+    const std::string& destination_name
+  ) : _arrival_time(arrival_time)
+    , _destination_name(destination_name) { }
+
+  const char* arrival_time() const {
+    return _arrival_time.c_str();
+  }
+
+private:
+  const std::string _arrival_time;
+  const std::string _destination_name; // not the code of the station
+};
+
+
+enum StatusEnum {
+  SUCCESSFUL_WITHOUT_DELAY = 0,
+  SUCCESSFUL_WITH_DELAY = 1,
+  FAILED_WITH_MESSAGE = 2,
+  UNKNOWN_STATUS = 3
+};
+
+struct StationArrivalInfo {
+public:
+  friend class MTRNextTrainHandler;
+
+private:
+  StationArrivalInfo(
+    cJSON* mtr_line_station_json,
+    cJSON* arrival_json,
+    const std::string& train_line_code,
+    const std::string& train_station_code
+  );
+
+  StatusEnum _status;
+  std::string _message; // only valid if status == FAILED_WITH_MESSAGE
+  std::string _train_line;
+  std::string _train_station;
+  std::vector<ArrivalInfo> _up_arrivals;
+  std::vector<ArrivalInfo> _down_arrivals;
+};

main/external/mtr/line_info.h

@@ -0,0 +1,45 @@
+#pragma once
+#include "cJSON.h"
+#include "esp_log.h"
+#include "external/mtr/station_info.h"
+#include "external/mtr/mtr.h"
+#include <string>
+
+static const char* LINE_INFO_TAG = "LineInfo";
+
+// Forward declaration
+class MTRNextTrainHandler;
+struct StationInfo;
+
+struct LineInfo {
+public:
+
+  // caller does not own the returned char pointers
+  const char* code() const {
+    return _code.c_str();
+  }
+  // caller does not own the returned char pointers
+  const char* color() const {
+    return _color.c_str();
+  }
+  size_t station_count() const {
+    return _stations.size();
+  }
+  // caller does not own the returned array or StationInfo pointers
+  const std::vector<StationInfo>* stations() const {
+    return &_stations;
+  }
+
+  friend class MTRNextTrainHandler;
+
+private:
+  // Caller transfers ownership of stations array and its contents to LineInfo
+  LineInfo(
+    cJSON* line_json
+  );
+
+  std::string _code;
+  std::string _color;
+  std::vector<StationInfo> _stations;
+};
+

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;
+};
+
+

main/external/mtr/station_info.h

@@ -0,0 +1,26 @@
+#pragma once
+#include "esp_log.h"
+#include "external/mtr/line_info.h"
+
+static const char* STATION_INFO_TAG = "StationInfo";
+
+// Forward declaration
+struct LineInfo;
+
+struct StationInfo {
+public:
+  StationInfo(cJSON* station_json);
+
+  const char* name() const { return _name.c_str(); }
+  const char* code() const { return _code.c_str(); }
+
+  friend class LineInfo;
+
+private:
+  // Caller transfers ownership of station_name and station_code to StationInfo
+  StationInfo(std::string& station_name, std::string& station_code)
+    : _name(station_name), _code(station_code) { }
+
+  std::string _name;
+  std::string _code;
+};